<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:media="http://search.yahoo.com/mrss/"><channel><title>BIND DNS: from first install to production | A DevOps Blog</title><link>https://blog.bsdserver.nl/series/bind-dns/</link><description>Hands-on DevOps and homelab content: Kubernetes clusters, self-hosted services, CI/CD pipelines and infrastructure as code, by Patrick de Ruiter of We Build Your Cloud.</description><language>en</language><image><url>https://blog.bsdserver.nl/images/app-icon.svg</url><title>A DevOps Blog</title><link>https://blog.bsdserver.nl/</link></image><lastBuildDate>Wed, 18 Nov 2026 09:00:00 +0100</lastBuildDate><atom:link href="https://blog.bsdserver.nl/series/bind-dns/rss/" rel="self" type="application/rss+xml"/><ttl>60</ttl><item><title>How to Setup BIND as a Recursive DNS Resolver</title><link>https://blog.bsdserver.nl/how-to-setup-bind-as-a-recursive-dns-resolver/</link><guid isPermaLink="false">693b6a5f79eb54000160a535</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:05:35 +0000</pubDate><description>A recursive DNS resolver is the workhorse of DNS infrastructure, handling client queries by recursively querying authoritative nameservers until it finds…</description><category>Linux</category><category>DNS</category><category>BIND</category><category>Networking</category><category>Security</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/bind-recursive-resolver.png" medium="image"/><content:encoded><![CDATA[<p>A recursive DNS resolver is the workhorse of DNS infrastructure, handling client queries by recursively querying authoritative nameservers until it finds the answer. BIND 9 is the most widely deployed DNS software and makes an excellent choice for running your own resolver.</p>
<p>This guide sets up a BIND resolver that only serves your own networks, validates DNSSEC, resists abuse, and logs what matters.</p>
<h2 id="why-run-your-own-resolver">Why Run Your Own Resolver? <a class="anchor" data-pagefind-ignore href="#why-run-your-own-resolver" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Privacy</strong>: your DNS queries stay on your network instead of going to third-party providers.</li>
<li><strong>Performance</strong>: local caching reduces latency for repeated queries.</li>
<li><strong>Control</strong>: you can implement custom filtering, logging, and policies.</li>
<li><strong>Reliability</strong>: no dependency on external DNS providers.</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> for an office, lab or data centre network where you want caching, logging or filtering under your own control.</li>
<li><strong>Skip it</strong> for a single machine or a small home network where your router or a public resolver is good enough.</li>
</ul>
<h2 id="how-it-works">How It Works <a class="anchor" data-pagefind-ignore href="#how-it-works" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Clients</td>
					<td>Your trusted networks</td>
					<td>Send every lookup to the resolver</td>
			</tr>
			<tr>
					<td>BIND resolver</td>
					<td>One server (or two for redundancy)</td>
					<td>Answers from cache, otherwise looks the name up, validates DNSSEC and caches the result</td>
			</tr>
			<tr>
					<td>Root, TLD and authoritative servers</td>
					<td>Internet</td>
					<td>Return referrals and final answers</td>
			</tr>
	</tbody>
</table>
<p>The flow: client asks the resolver → cache hit? answer straight away → otherwise root → TLD → authoritative server → validate → cache → answer.</p>
<h2 id="installation">Installation <a class="anchor" data-pagefind-ignore href="#installation" aria-label="Link to this section">#</a></h2>
<p>The packages install the server, the <code>named-checkconf</code> tool and <code>dig</code>. Enabling the service now means it also starts at boot.</p>
<p><strong>Debian/Ubuntu:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo apt update
</span></span><span class="line"><span class="cl">sudo apt install -y bind9 bind9utils bind9-doc dnsutils
</span></span></code></pre></div><p><strong>RHEL/Rocky/AlmaLinux:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo dnf install -y <span class="nb">bind</span> bind-utils
</span></span></code></pre></div><p>Enable and start the service:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo systemctl <span class="nb">enable</span> --now named
</span></span></code></pre></div><h2 id="basic-configuration">Basic Configuration <a class="anchor" data-pagefind-ignore href="#basic-configuration" aria-label="Link to this section">#</a></h2>
<p>The main configuration file is <code>/etc/bind/named.conf</code> (Debian) or <code>/etc/named.conf</code> (RHEL). The resolver settings go in the <code>options</code> block.</p>
<h3 id="define-access-control-lists">Define Access Control Lists <a class="anchor" data-pagefind-ignore href="#define-access-control-lists" aria-label="Link to this section">#</a></h3>
<p>An open resolver gets abused for amplification attacks within days. The <code>trusted</code> ACL names the networks that may use it; the options refer to it. Create or edit <code>/etc/bind/named.conf.options</code>:</p>
<ul>
<li><code>allow-recursion</code>, <code>allow-query</code>, <code>allow-query-cache</code> <code>{ trusted; }</code>: only trusted clients may query, recurse, or read the cache.</li>
<li><code>allow-transfer { none; }</code>: a resolver hosts no zones to transfer.</li>
<li><code>dnssec-validation auto</code>: validate signed answers with the built-in root trust anchor.</li>
<li><code>max-cache-size</code>: memory cap for the cache. Raise it for many clients.</li>
<li><code>max-cache-ttl</code> / <code>max-ncache-ttl</code>: upper limits for how long positive and negative (NXDOMAIN) answers are cached.</li>
<li><code>minimal-responses yes</code> and <code>version &quot;not disclosed&quot;</code>: smaller answers, no version leak.</li>
<li><code>querylog no</code>: query logging is off by default; it is noisy. Turn it on with <code>rndc querylog</code> when debugging.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bind" data-lang="bind"><span class="line"><span class="cl"><span class="err">//</span><span class="w"> </span><span class="err">Define</span><span class="w"> </span><span class="err">trusted</span><span class="w"> </span><span class="err">networks</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">acl</span><span class="w"> </span><span class="err">&#34;trusted&#34;</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">localhost</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">localnets</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="mi">192.168.0.0</span><span class="err">/</span><span class="sc">16</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="mi">10.0.0.0</span><span class="err">/</span><span class="sc">8</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="mi">172.16.0.0</span><span class="err">/</span><span class="sc">12</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">options</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">directory</span><span class="w"> </span><span class="err">&#34;/var/cache/bind&#34;</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Network</span><span class="w"> </span><span class="err">interface</span><span class="w"> </span><span class="err">settings</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">listen-on</span><span class="w"> </span><span class="err">port</span><span class="w"> </span><span class="sc">53</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">any</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">listen-on-v6</span><span class="w"> </span><span class="err">port</span><span class="w"> </span><span class="sc">53</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">any</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Recursion</span><span class="w"> </span><span class="err">settings</span><span class="w"> </span><span class="err">-</span><span class="w"> </span><span class="err">CRITICAL</span><span class="w"> </span><span class="err">for</span><span class="w"> </span><span class="err">security</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">recursion</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">allow-recursion</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">trusted</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">allow-query</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">trusted</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">allow-query-cache</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">trusted</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Disable</span><span class="w"> </span><span class="err">zone</span><span class="w"> </span><span class="err">transfers</span><span class="w"> </span><span class="p">(</span><span class="err">not</span><span class="w"> </span><span class="err">needed</span><span class="w"> </span><span class="err">for</span><span class="w"> </span><span class="err">resolver</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">allow-transfer</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">none</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">DNSSEC</span><span class="w"> </span><span class="err">validation</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">dnssec-validation</span><span class="w"> </span><span class="err">auto</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Source</span><span class="w"> </span><span class="err">port</span><span class="w"> </span><span class="err">randomization</span><span class="w"> </span><span class="err">is</span><span class="w"> </span><span class="err">on</span><span class="w"> </span><span class="err">by</span><span class="w"> </span><span class="err">default</span><span class="w"> </span><span class="err">-</span><span class="w"> </span><span class="err">don&#39;t</span><span class="w"> </span><span class="err">set</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">query-source</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="err">port</span><span class="w"> </span><span class="p">(</span><span class="err">the</span><span class="w"> </span><span class="err">&#39;port&#39;</span><span class="w"> </span><span class="err">token</span><span class="w"> </span><span class="err">is</span><span class="w"> </span><span class="err">deprecated</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Performance</span><span class="w"> </span><span class="err">tuning</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">max-cache-size</span><span class="w"> </span><span class="sc">256m</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">max-cache-ttl</span><span class="w"> </span><span class="sc">86400</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">max-ncache-ttl</span><span class="w"> </span><span class="sc">3600</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Prevent</span><span class="w"> </span><span class="err">amplification</span><span class="w"> </span><span class="err">attacks</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">minimal-responses</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Hide</span><span class="w"> </span><span class="err">version</span><span class="w"> </span><span class="err">string</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">version</span><span class="w"> </span><span class="err">&#34;not</span><span class="w"> </span><span class="err">disclosed&#34;</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Logging</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">querylog</span><span class="w"> </span><span class="err">no</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span></code></pre></div><h3 id="security-hardening">Security Hardening <a class="anchor" data-pagefind-ignore href="#security-hardening" aria-label="Link to this section">#</a></h3>
<p>These options go into the same <code>options</code> block and limit what the resolver will answer.</p>
<ul>
<li><code>deny-answer-addresses</code>: drop answers from the internet that point at loopback addresses, a defence against DNS rebinding.</li>
<li><code>rate-limit</code>: Response Rate Limiting caps identical responses per client, so the resolver is a poor amplifier.</li>
<li><code>empty-zones-enable yes</code>: answer reverse lookups for private and reserved ranges locally instead of leaking them upstream.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bind" data-lang="bind"><span class="line"><span class="cl"><span class="nc">options</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="err">previous</span><span class="w"> </span><span class="err">options</span><span class="w"> </span><span class="err">...</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Prevent</span><span class="w"> </span><span class="err">loopback/localhost</span><span class="w"> </span><span class="err">attacks</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">deny-answer-addresses</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="mi">127.0.0.0</span><span class="err">/</span><span class="sc">8</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">::</span><span class="sc">1</span><span class="err">/</span><span class="sc">128</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">}</span><span class="w"> </span><span class="err">except-from</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">&#34;none&#34;</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Rate</span><span class="w"> </span><span class="err">limiting</span><span class="w"> </span><span class="err">to</span><span class="w"> </span><span class="err">prevent</span><span class="w"> </span><span class="err">abuse</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">rate-limit</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">responses-per-second</span><span class="w"> </span><span class="sc">10</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">window</span><span class="w"> </span><span class="sc">5</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Keep</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">built-in</span><span class="w"> </span><span class="err">empty</span><span class="w"> </span><span class="err">zones</span><span class="w"> </span><span class="err">for</span><span class="w"> </span><span class="err">RFC</span><span class="w"> </span><span class="sc">1918</span><span class="w"> </span><span class="err">and</span><span class="w"> </span><span class="err">other</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">reserved</span><span class="w"> </span><span class="err">reverse</span><span class="w"> </span><span class="err">ranges</span><span class="w"> </span><span class="p">(</span><span class="err">stops</span><span class="w"> </span><span class="err">those</span><span class="w"> </span><span class="err">queries</span><span class="w"> </span><span class="err">leaking</span><span class="w"> </span><span class="err">upstream</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">empty-zones-enable</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span></code></pre></div><h2 id="forwarding-configuration-optional">Forwarding Configuration (Optional) <a class="anchor" data-pagefind-ignore href="#forwarding-configuration-optional" aria-label="Link to this section">#</a></h2>
<p>By default the resolver does full recursion from the root. Forwarders send cache misses to upstream resolvers instead, which helps when outbound DNS is restricted to a few servers.</p>
<table>
	<thead>
			<tr>
					<th>Mode</th>
					<th>Behaviour</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>No forwarders</td>
					<td>Full recursion from the root</td>
					<td>Most setups; no third party sees your queries</td>
			</tr>
			<tr>
					<td><code>forward first</code></td>
					<td>Ask forwarders, recurse yourself if they fail</td>
					<td>Upstream preferred, with a fallback</td>
			</tr>
			<tr>
					<td><code>forward only</code></td>
					<td>Only ask forwarders</td>
					<td>Networks where outbound DNS must go through specific servers</td>
			</tr>
	</tbody>
</table>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bind" data-lang="bind"><span class="line"><span class="cl"><span class="nc">options</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="err">previous</span><span class="w"> </span><span class="err">options</span><span class="w"> </span><span class="err">...</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Forward</span><span class="w"> </span><span class="err">to</span><span class="w"> </span><span class="err">upstream</span><span class="w"> </span><span class="err">resolvers</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">forwarders</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="mi">1.1.1.1</span><span class="c">;        // Cloudflare</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="mi">8.8.8.8</span><span class="c">;        // Google</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="mi">9.9.9.9</span><span class="c">;        // Quad9</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Forward</span><span class="w"> </span><span class="err">first,</span><span class="w"> </span><span class="err">then</span><span class="w"> </span><span class="err">recurse</span><span class="w"> </span><span class="err">if</span><span class="w"> </span><span class="err">forwarders</span><span class="w"> </span><span class="err">fail</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">forward</span><span class="w"> </span><span class="err">first</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span></code></pre></div><p>Use <code>forward only;</code> if you want to exclusively use forwarders without fallback recursion.</p>
<h2 id="logging-configuration">Logging Configuration <a class="anchor" data-pagefind-ignore href="#logging-configuration" aria-label="Link to this section">#</a></h2>
<p>Separate channels keep queries, security events and general messages apart. Add to your configuration:</p>
<table>
	<thead>
			<tr>
					<th>Channel</th>
					<th>Categories</th>
					<th>What you find there</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>default_log</code></td>
					<td><code>default</code></td>
					<td>Startup, errors, general messages</td>
			</tr>
			<tr>
					<td><code>query_log</code></td>
					<td><code>queries</code></td>
					<td>Every query, once query logging is on</td>
			</tr>
			<tr>
					<td><code>security_log</code></td>
					<td><code>security</code>, <code>client</code></td>
					<td>Denied queries and client problems</td>
			</tr>
	</tbody>
</table>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bind" data-lang="bind"><span class="line"><span class="cl"><span class="nc">logging</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">channel</span><span class="w"> </span><span class="err">default_log</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">file</span><span class="w"> </span><span class="err">&#34;/var/log/named/</span><span class="nc">default.log</span><span class="err">&#34;</span><span class="w"> </span><span class="err">versions</span><span class="w"> </span><span class="sc">3</span><span class="w"> </span><span class="err">size</span><span class="w"> </span><span class="sc">5m</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">severity</span><span class="w"> </span><span class="err">info</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">print-time</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">print-severity</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">print-category</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">channel</span><span class="w"> </span><span class="err">query_log</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">file</span><span class="w"> </span><span class="err">&#34;/var/log/named/</span><span class="nc">query.log</span><span class="err">&#34;</span><span class="w"> </span><span class="err">versions</span><span class="w"> </span><span class="sc">5</span><span class="w"> </span><span class="err">size</span><span class="w"> </span><span class="sc">10m</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">severity</span><span class="w"> </span><span class="err">info</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">print-time</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">channel</span><span class="w"> </span><span class="err">security_log</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">file</span><span class="w"> </span><span class="err">&#34;/var/log/named/</span><span class="nc">security.log</span><span class="err">&#34;</span><span class="w"> </span><span class="err">versions</span><span class="w"> </span><span class="sc">3</span><span class="w"> </span><span class="err">size</span><span class="w"> </span><span class="sc">5m</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">severity</span><span class="w"> </span><span class="err">info</span><span class="c">;    // denied queries are logged at info</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">print-time</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">print-severity</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">category</span><span class="w"> </span><span class="err">default</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">default_log</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">category</span><span class="w"> </span><span class="err">queries</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">query_log</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">category</span><span class="w"> </span><span class="err">security</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">security_log</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">category</span><span class="w"> </span><span class="err">client</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">security_log</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span></code></pre></div><p>Create the log directory, owned by the BIND user, before restarting:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo mkdir -p /var/log/named
</span></span><span class="line"><span class="cl">sudo chown bind:bind /var/log/named
</span></span></code></pre></div><h2 id="root-hints">Root Hints <a class="anchor" data-pagefind-ignore href="#root-hints" aria-label="Link to this section">#</a></h2>
<p>Root hints tell the resolver where the root servers are, the starting point for every recursion. BIND usually includes these, but you can download the current list:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo curl -o /var/cache/bind/named.root https://www.internic.net/domain/named.root
</span></span></code></pre></div><p>Both Debian/Ubuntu and RHEL already define the hint zone: Debian/Ubuntu in <code>/etc/bind/named.conf.default-zones</code> (pointing at <code>/usr/share/dns/root.hints</code>), RHEL in <code>/etc/named.conf</code> (<code>named.ca</code>). Don&rsquo;t add a second <code>zone &quot;.&quot;</code>, because <code>named-checkconf</code> rejects it with <code>zone '.': already exists</code>. Instead, change the <code>file</code> line of the existing hint zone:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bind" data-lang="bind"><span class="line"><span class="cl"><span class="nc">zone</span><span class="w"> </span><span class="err">&#34;.&#34;</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">type</span><span class="w"> </span><span class="err">hint</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">file</span><span class="w"> </span><span class="err">&#34;/var/cache/bind/</span><span class="nc">named.root</span><span class="err">&#34;</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span></code></pre></div><h2 id="validate-and-start">Validate and Start <a class="anchor" data-pagefind-ignore href="#validate-and-start" aria-label="Link to this section">#</a></h2>
<p>Always check the configuration first: a restart with a broken configuration leaves your clients without DNS.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo named-checkconf
</span></span></code></pre></div><p>If there are no errors, restart BIND:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo systemctl restart named
</span></span></code></pre></div><p>Check the status:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo systemctl status named
</span></span><span class="line"><span class="cl">sudo journalctl -u named -f
</span></span></code></pre></div><h2 id="testing">Testing <a class="anchor" data-pagefind-ignore href="#testing" aria-label="Link to this section">#</a></h2>
<p>Test from a client machine on a trusted network. Each check proves one part of the setup:</p>
<ul>
<li><code>google.com</code>: recursion and caching work.</li>
<li><code>dnssec-failed.org</code>: a deliberately broken DNSSEC domain. SERVFAIL proves validation is on.</li>
<li><code>version.bind</code>: should return &ldquo;not disclosed&rdquo;.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Test basic resolution</span>
</span></span><span class="line"><span class="cl">dig @your-resolver-ip google.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test DNSSEC validation</span>
</span></span><span class="line"><span class="cl">dig @your-resolver-ip dnssec-failed.org
</span></span><span class="line"><span class="cl"><span class="c1"># Should return SERVFAIL (DNSSEC validation failure)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check that the version string is hidden (&#34;not disclosed&#34;)</span>
</span></span><span class="line"><span class="cl">dig @your-resolver-ip +short version.bind txt chaos
</span></span></code></pre></div><p>The DNS-OARC port randomization test (<code>porttest.dns-oarc.net</code>) that older guides mention has been retired; the name now returns NXDOMAIN. BIND randomizes query source ports by default, so there is nothing to enable as long as you don&rsquo;t pin <code>query-source</code> to a fixed port.</p>
<h2 id="firewall-configuration">Firewall Configuration <a class="anchor" data-pagefind-ignore href="#firewall-configuration" aria-label="Link to this section">#</a></h2>
<p>The firewall is a second line behind the ACL: only trusted networks reach port 53. DNS uses both UDP and TCP.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># UFW (Ubuntu)</span>
</span></span><span class="line"><span class="cl">sudo ufw allow from 192.168.0.0/16 to any port <span class="m">53</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># firewalld (RHEL)</span>
</span></span><span class="line"><span class="cl">sudo firewall-cmd --permanent --add-service<span class="o">=</span>dns
</span></span><span class="line"><span class="cl">sudo firewall-cmd --reload
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># iptables</span>
</span></span><span class="line"><span class="cl">sudo iptables -A INPUT -p udp --dport <span class="m">53</span> -s 192.168.0.0/16 -j ACCEPT
</span></span><span class="line"><span class="cl">sudo iptables -A INPUT -p tcp --dport <span class="m">53</span> -s 192.168.0.0/16 -j ACCEPT
</span></span></code></pre></div><h2 id="complete-configuration-example">Complete Configuration Example <a class="anchor" data-pagefind-ignore href="#complete-configuration-example" aria-label="Link to this section">#</a></h2>
<p>All of the above in one <code>/etc/bind/named.conf.options</code>, for reference:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bind" data-lang="bind"><span class="line"><span class="cl"><span class="nc">acl</span><span class="w"> </span><span class="err">&#34;trusted&#34;</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">localhost</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">localnets</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="mi">192.168.0.0</span><span class="err">/</span><span class="sc">16</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="mi">10.0.0.0</span><span class="err">/</span><span class="sc">8</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">options</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">directory</span><span class="w"> </span><span class="err">&#34;/var/cache/bind&#34;</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">listen-on</span><span class="w"> </span><span class="err">port</span><span class="w"> </span><span class="sc">53</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">any</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">listen-on-v6</span><span class="w"> </span><span class="err">port</span><span class="w"> </span><span class="sc">53</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">any</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">recursion</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">allow-recursion</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">trusted</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">allow-query</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">trusted</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">allow-query-cache</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">trusted</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">allow-transfer</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">none</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">dnssec-validation</span><span class="w"> </span><span class="err">auto</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">max-cache-size</span><span class="w"> </span><span class="sc">256m</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">max-cache-ttl</span><span class="w"> </span><span class="sc">86400</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">max-ncache-ttl</span><span class="w"> </span><span class="sc">3600</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">minimal-responses</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">version</span><span class="w"> </span><span class="err">&#34;not</span><span class="w"> </span><span class="err">disclosed&#34;</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">deny-answer-addresses</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="mi">127.0.0.0</span><span class="err">/</span><span class="sc">8</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">::</span><span class="sc">1</span><span class="err">/</span><span class="sc">128</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">}</span><span class="w"> </span><span class="err">except-from</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">&#34;none&#34;</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">rate-limit</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">responses-per-second</span><span class="w"> </span><span class="sc">10</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">window</span><span class="w"> </span><span class="sc">5</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">logging</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">channel</span><span class="w"> </span><span class="err">default_log</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">file</span><span class="w"> </span><span class="err">&#34;/var/log/named/</span><span class="nc">default.log</span><span class="err">&#34;</span><span class="w"> </span><span class="err">versions</span><span class="w"> </span><span class="sc">3</span><span class="w"> </span><span class="err">size</span><span class="w"> </span><span class="sc">5m</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">severity</span><span class="w"> </span><span class="err">info</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">print-time</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">print-severity</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">category</span><span class="w"> </span><span class="err">default</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">default_log</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span></code></pre></div><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Likely cause / fix</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Clients get <code>REFUSED</code></td>
					<td>Client network missing from the <code>trusted</code> ACL</td>
			</tr>
			<tr>
					<td><code>named</code> fails to start after adding logging</td>
					<td><code>/var/log/named</code> missing or wrong owner</td>
			</tr>
			<tr>
					<td><code>zone '.': already exists</code></td>
					<td>A second root hint zone was added; edit the existing one</td>
			</tr>
			<tr>
					<td>Valid domains return SERVFAIL</td>
					<td>DNSSEC failure or no outbound DNS; check <code>security.log</code> and the firewall</td>
			</tr>
	</tbody>
</table>
<h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub:
<a href="https://github.com/pderuiter/blog-bind-recursive-resolver" rel="noopener">pderuiter/blog-bind-recursive-resolver</a>. It creates an Ubuntu 24.04 VM on Proxmox and configures the resolver from this post, with the trusted ACL, hardening, logging, fresh root hints and optional forwarders; fill in <code>terraform.tfvars</code>, run <code>terraform apply</code>, then <code>ansible-playbook site.yml</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>You now have a secure BIND recursive resolver. Key points to remember:</p>
<ul>
<li><strong>Never run an open resolver</strong>: always restrict access with ACLs.</li>
<li><strong>Enable DNSSEC validation</strong>: protects against cache poisoning.</li>
<li><strong>Use rate limiting</strong>: prevents amplification attacks.</li>
<li><strong>Monitor logs</strong>: watch for unusual activity.</li>
<li><strong>Keep BIND updated</strong>: security patches are released regularly.</li>
</ul>
<p>In the next posts, we&rsquo;ll cover setting up BIND as an <a href="https://blog.bsdserver.nl/how-to-setup-bind-as-an-authoritative-dns-server/">authoritative server</a>, configuring DNSSEC, and implementing DNS over TLS/HTTPS.</p>
]]></content:encoded></item><item><title>How to Setup BIND as an Authoritative DNS Server</title><link>https://blog.bsdserver.nl/how-to-setup-bind-as-an-authoritative-dns-server/</link><guid isPermaLink="false">693b6abb79eb54000160a53e</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:07:07 +0000</pubDate><description>An authoritative DNS server is the definitive source of DNS records for the domains it hosts.</description><category>Linux</category><category>DNS</category><category>BIND</category><category>Networking</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/bind-authoritative-dns.png" medium="image"/><content:encoded><![CDATA[<p>An authoritative DNS server is the definitive source of DNS records for the domains it hosts. Unlike recursive resolvers that query other servers, authoritative servers directly answer queries with the records they maintain.</p>
<p>This guide configures BIND 9 as an authoritative-only server: a master that holds the zone files, a slave that copies them by zone transfer, forward and reverse zones, logging and a firewall.</p>
<h2 id="why-authoritative-only">Why Authoritative-Only? <a class="anchor" data-pagefind-ignore href="#why-authoritative-only" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Smaller attack surface</strong>: no recursion means the server cannot be abused as an open resolver.</li>
<li><strong>Predictable load</strong>: it only answers for its own zones, never chases answers elsewhere.</li>
<li><strong>Clear roles</strong>: resolvers for your clients, authoritative servers for the world.</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> when you host your own domains (public or internal) and want control over the records.</li>
<li><strong>Skip it</strong> if your registrar or a managed DNS provider already serves your zones and you do not need in-house control.</li>
</ul>
<h3 id="authoritative-vs-recursive">Authoritative vs recursive <a class="anchor" data-pagefind-ignore href="#authoritative-vs-recursive" aria-label="Link to this section">#</a></h3>
<table>
	<thead>
			<tr>
					<th></th>
					<th>Authoritative</th>
					<th>Recursive resolver</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Answers for</td>
					<td>Only the zones it hosts</td>
					<td>Any name, by asking other servers</td>
			</tr>
			<tr>
					<td>Clients</td>
					<td>Anyone on the internet (or your network)</td>
					<td>Your own clients only</td>
			</tr>
			<tr>
					<td>Recursion</td>
					<td>Off</td>
					<td>On</td>
			</tr>
			<tr>
					<td>Covered in</td>
					<td>This post</td>
					<td><a href="https://blog.bsdserver.nl/how-to-setup-bind-as-a-recursive-dns-resolver/">Recursive resolver post</a></td>
			</tr>
	</tbody>
</table>
<h2 id="architecture-overview">Architecture Overview <a class="anchor" data-pagefind-ignore href="#architecture-overview" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Master (<code>type primary</code>)</td>
					<td><code>10.0.0.1</code> (ns1)</td>
					<td>Holds the zone files you edit. Notifies the slave on changes and allows it to transfer.</td>
			</tr>
			<tr>
					<td>Slave (<code>type secondary</code>)</td>
					<td><code>10.0.0.2</code> (ns2)</td>
					<td>Copies the zones from the master and answers queries too.</td>
			</tr>
	</tbody>
</table>
<p>The flow: you edit a zone file on the master and bump the serial → <code>rndc reload</code> → the master sends a NOTIFY → the slave sees a higher serial and transfers the zone → both answer with the new records.</p>
<h2 id="installation">Installation <a class="anchor" data-pagefind-ignore href="#installation" aria-label="Link to this section">#</a></h2>
<p>The package names differ per distribution; both install the server and the <code>dig</code>/<code>named-check*</code> tools.</p>
<p><strong>Debian/Ubuntu:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo apt update
</span></span><span class="line"><span class="cl">sudo apt install -y bind9 bind9utils dnsutils
</span></span></code></pre></div><p><strong>RHEL/Rocky/AlmaLinux:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo dnf install -y <span class="nb">bind</span> bind-utils
</span></span></code></pre></div><h2 id="authoritative-only-configuration">Authoritative-Only Configuration <a class="anchor" data-pagefind-ignore href="#authoritative-only-configuration" aria-label="Link to this section">#</a></h2>
<p>The global <code>options</code> turn recursion off and set safe defaults for every zone. Edit <code>/etc/bind/named.conf.options</code> (Debian) or <code>/etc/named.conf</code> (RHEL).</p>
<ul>
<li><code>recursion no</code> and <code>allow-recursion { none; }</code>: the server only answers for its own zones.</li>
<li><code>allow-query { any; }</code>: anyone may ask, as expected for a public authoritative server.</li>
<li><code>allow-transfer { none; }</code>: no zone transfers by default; each zone opens it for its slave.</li>
<li><code>version &quot;not disclosed&quot;</code>: hides the BIND version from <code>version.bind</code> queries.</li>
<li><code>minimal-responses yes</code>: leaves out optional extra records, so answers are smaller.</li>
<li><code>rate-limit</code>: Response Rate Limiting. Caps identical responses per client, which blunts DNS amplification attacks.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bind" data-lang="bind"><span class="line"><span class="cl"><span class="nc">options</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">directory</span><span class="w"> </span><span class="err">&#34;/var/cache/bind&#34;</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Listen</span><span class="w"> </span><span class="err">on</span><span class="w"> </span><span class="err">all</span><span class="w"> </span><span class="err">interfaces</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">listen-on</span><span class="w"> </span><span class="err">port</span><span class="w"> </span><span class="sc">53</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">any</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">listen-on-v6</span><span class="w"> </span><span class="err">port</span><span class="w"> </span><span class="sc">53</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">any</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Disable</span><span class="w"> </span><span class="err">recursion</span><span class="w"> </span><span class="err">-</span><span class="w"> </span><span class="err">this</span><span class="w"> </span><span class="err">is</span><span class="w"> </span><span class="err">authoritative</span><span class="w"> </span><span class="err">only</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">recursion</span><span class="w"> </span><span class="err">no</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">allow-recursion</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">none</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Allow</span><span class="w"> </span><span class="err">queries</span><span class="w"> </span><span class="err">from</span><span class="w"> </span><span class="err">anyone</span><span class="w"> </span><span class="p">(</span><span class="err">public</span><span class="w"> </span><span class="err">authoritative</span><span class="w"> </span><span class="err">server</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">allow-query</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">any</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Disable</span><span class="w"> </span><span class="err">zone</span><span class="w"> </span><span class="err">transfers</span><span class="w"> </span><span class="err">by</span><span class="w"> </span><span class="err">default</span><span class="w"> </span><span class="p">(</span><span class="err">override</span><span class="w"> </span><span class="err">per-zone</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">allow-transfer</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">none</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">DNSSEC</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">dnssec-validation</span><span class="w"> </span><span class="err">auto</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Security</span><span class="w"> </span><span class="err">hardening</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">version</span><span class="w"> </span><span class="err">&#34;not</span><span class="w"> </span><span class="err">disclosed&#34;</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">minimal-responses</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Rate</span><span class="w"> </span><span class="err">limiting</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">rate-limit</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">responses-per-second</span><span class="w"> </span><span class="sc">15</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">window</span><span class="w"> </span><span class="sc">5</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span></code></pre></div><h2 id="zone-configuration">Zone Configuration <a class="anchor" data-pagefind-ignore href="#zone-configuration" aria-label="Link to this section">#</a></h2>
<p>Each zone gets a <code>zone</code> block that says which role this server has for it. Define them in <code>/etc/bind/named.conf.local</code> (Debian) or add them to <code>/etc/named.conf</code> (RHEL).</p>
<table>
	<thead>
			<tr>
					<th>Role</th>
					<th><code>type</code> keyword</th>
					<th>Gets its data from</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Master</td>
					<td><code>primary</code> (older name: <code>master</code>)</td>
					<td>The zone file on disk</td>
			</tr>
			<tr>
					<td>Slave</td>
					<td><code>secondary</code> (older name: <code>slave</code>)</td>
					<td>Zone transfers from the master</td>
			</tr>
	</tbody>
</table>
<h3 id="master-zone">Master Zone <a class="anchor" data-pagefind-ignore href="#master-zone" aria-label="Link to this section">#</a></h3>
<p>On the master, both zones point at a local file and open transfers only for the slave.</p>
<ul>
<li><code>allow-transfer { 10.0.0.2; }</code>: only the slave may copy the zone.</li>
<li><code>also-notify { 10.0.0.2; }</code>: send a NOTIFY to the slave when the zone changes, so it does not wait for its refresh timer.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bind" data-lang="bind"><span class="line"><span class="cl"><span class="nc">zone</span><span class="w"> </span><span class="err">&#34;</span><span class="nc">example.com</span><span class="err">&#34;</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">type</span><span class="w"> </span><span class="err">primary</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">file</span><span class="w"> </span><span class="err">&#34;/var/lib/bind/zones/</span><span class="nc">example.com.zone</span><span class="err">&#34;</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">allow-transfer</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="mi">10.0.0.2</span><span class="c">; };  // Secondary server IP</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">also-notify</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="mi">10.0.0.2</span><span class="c">; };     // Notify secondary on changes</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">//</span><span class="w"> </span><span class="err">Reverse</span><span class="w"> </span><span class="err">DNS</span><span class="w"> </span><span class="err">zone</span><span class="w"> </span><span class="err">for</span><span class="w"> </span><span class="mi">192.168.1.0</span><span class="err">/</span><span class="sc">24</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">zone</span><span class="w"> </span><span class="err">&#34;</span><span class="sc">1</span><span class="nc">.168.192.in-addr.arpa</span><span class="err">&#34;</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">type</span><span class="w"> </span><span class="err">primary</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">file</span><span class="w"> </span><span class="err">&#34;/var/lib/bind/zones/</span><span class="sc">192</span><span class="nc">.168.1.rev</span><span class="err">&#34;</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">allow-transfer</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="mi">10.0.0.2</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">also-notify</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="mi">10.0.0.2</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span></code></pre></div><h3 id="slave-zone">Slave Zone <a class="anchor" data-pagefind-ignore href="#slave-zone" aria-label="Link to this section">#</a></h3>
<p>On the slave, <code>primaries</code> names the master to transfer from. The <code>file</code> is where BIND stores the transferred copy, so the slave can answer after a restart without a new transfer.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bind" data-lang="bind"><span class="line"><span class="cl"><span class="nc">zone</span><span class="w"> </span><span class="err">&#34;</span><span class="nc">example.com</span><span class="err">&#34;</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">type</span><span class="w"> </span><span class="err">secondary</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">file</span><span class="w"> </span><span class="err">&#34;/var/lib/bind/zones/</span><span class="nc">example.com.zone</span><span class="err">&#34;</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">primaries</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="mi">10.0.0.1</span><span class="c">; };  // Primary server IP</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span></code></pre></div><h2 id="creating-zone-files">Creating Zone Files <a class="anchor" data-pagefind-ignore href="#creating-zone-files" aria-label="Link to this section">#</a></h2>
<p>Zone files live in <code>/var/lib/bind/zones</code>. BIND must own the directory: a slave writes its transferred copies there.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo mkdir -p /var/lib/bind/zones
</span></span><span class="line"><span class="cl">sudo chown bind:bind /var/lib/bind/zones
</span></span></code></pre></div><h3 id="forward-zone-file">Forward Zone File <a class="anchor" data-pagefind-ignore href="#forward-zone-file" aria-label="Link to this section">#</a></h3>
<p>The forward zone maps names to addresses. Create <code>/var/lib/bind/zones/example.com.zone</code>:</p>
<table>
	<thead>
			<tr>
					<th>Record</th>
					<th>Used for here</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>SOA</code></td>
					<td>Zone metadata and timers (see below)</td>
			</tr>
			<tr>
					<td><code>NS</code> + <code>A</code> for ns1/ns2</td>
					<td>The zone&rsquo;s nameservers and their addresses</td>
			</tr>
			<tr>
					<td><code>MX</code></td>
					<td>Mail servers; lower preference number is tried first</td>
			</tr>
			<tr>
					<td><code>A</code> / <code>AAAA</code></td>
					<td>IPv4 / IPv6 addresses</td>
			</tr>
			<tr>
					<td><code>CNAME</code></td>
					<td>Aliases pointing at another name</td>
			</tr>
			<tr>
					<td><code>TXT</code></td>
					<td>SPF and DMARC policies for mail</td>
			</tr>
	</tbody>
</table>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-dns" data-lang="dns"><span class="line"><span class="cl"><span class="na">$TTL</span><span class="w"> </span><span class="sc">86400</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="na">$ORIGIN</span><span class="w"> </span><span class="py">example.com.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">@</span><span class="w">   </span><span class="k">IN</span><span class="w">  </span><span class="k">SOA</span><span class="w"> </span><span class="py">ns1.example.com. admin.example.com. </span><span class="p">(</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="sc">2024121201</span><span class="w">  </span><span class="c">; Serial (YYYYMMDDNN)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="sc">3600</span><span class="w">        </span><span class="c">; Refresh (1 hour)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="sc">1800</span><span class="w">        </span><span class="c">; Retry (30 minutes)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="sc">604800</span><span class="w">      </span><span class="c">; Expire (1 week)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="sc">86400</span><span class="w">       </span><span class="c">; Minimum TTL (1 day)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c">; Nameservers</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">@</span><span class="w">           </span><span class="k">IN</span><span class="w">  </span><span class="k">NS</span><span class="w">      </span><span class="py">ns1.example.com.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">@</span><span class="w">           </span><span class="k">IN</span><span class="w">  </span><span class="k">NS</span><span class="w">      </span><span class="py">ns2.example.com.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c">; Nameserver A records</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">ns1</span><span class="w">         </span><span class="k">IN</span><span class="w">  </span><span class="k">A</span><span class="w">       </span><span class="mi">10.0.0.1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">ns2</span><span class="w">         </span><span class="k">IN</span><span class="w">  </span><span class="k">A</span><span class="w">       </span><span class="mi">10.0.0.2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c">; Mail servers</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">@</span><span class="w">           </span><span class="k">IN</span><span class="w">  </span><span class="k">MX</span><span class="w">  </span><span class="sc">10</span><span class="w">  </span><span class="py">mail.example.com.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">@</span><span class="w">           </span><span class="k">IN</span><span class="w">  </span><span class="k">MX</span><span class="w">  </span><span class="sc">20</span><span class="w">  </span><span class="py">mail2.example.com.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c">; A records</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">@</span><span class="w">           </span><span class="k">IN</span><span class="w">  </span><span class="k">A</span><span class="w">       </span><span class="mi">93.184.216.34</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">www</span><span class="w">         </span><span class="k">IN</span><span class="w">  </span><span class="k">A</span><span class="w">       </span><span class="mi">93.184.216.34</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">mail</span><span class="w">        </span><span class="k">IN</span><span class="w">  </span><span class="k">A</span><span class="w">       </span><span class="mi">10.0.0.10</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">mail2</span><span class="w">       </span><span class="k">IN</span><span class="w">  </span><span class="k">A</span><span class="w">       </span><span class="mi">10.0.0.11</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">ftp</span><span class="w">         </span><span class="k">IN</span><span class="w">  </span><span class="k">A</span><span class="w">       </span><span class="mi">10.0.0.20</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c">; CNAME records</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">webmail</span><span class="w">     </span><span class="k">IN</span><span class="w">  </span><span class="k">CNAME</span><span class="w">   </span><span class="py">mail.example.com.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">smtp</span><span class="w">        </span><span class="k">IN</span><span class="w">  </span><span class="k">CNAME</span><span class="w">   </span><span class="py">mail.example.com.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">imap</span><span class="w">        </span><span class="k">IN</span><span class="w">  </span><span class="k">CNAME</span><span class="w">   </span><span class="py">mail.example.com.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c">; TXT records for email authentication</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">@</span><span class="w">           </span><span class="k">IN</span><span class="w">  </span><span class="k">TXT</span><span class="w">     </span><span class="err">&#34;v=spf1</span><span class="w"> </span><span class="err">mx</span><span class="w"> </span><span class="err">a:</span><span class="nc">mail.example.com</span><span class="w"> </span><span class="err">-all&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">_dmarc</span><span class="w">      </span><span class="k">IN</span><span class="w">  </span><span class="k">TXT</span><span class="w">     </span><span class="err">&#34;v=DMARC1</span><span class="c">; p=reject; rua=mailto:dmarc@example.com&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c">; AAAA records (IPv6)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">@</span><span class="w">           </span><span class="k">IN</span><span class="w">  </span><span class="k">AAAA</span><span class="w">    </span><span class="il">2001:db8::1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">www</span><span class="w">         </span><span class="k">IN</span><span class="w">  </span><span class="k">AAAA</span><span class="w">    </span><span class="il">2001:db8::1</span><span class="w">
</span></span></span></code></pre></div><h3 id="reverse-zone-file">Reverse Zone File <a class="anchor" data-pagefind-ignore href="#reverse-zone-file" aria-label="Link to this section">#</a></h3>
<p>The reverse zone maps addresses back to names with <code>PTR</code> records, used by <code>dig -x</code> and by mail servers checking the sender. The record name is the last octet. Create <code>/var/lib/bind/zones/192.168.1.rev</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-dns" data-lang="dns"><span class="line"><span class="cl"><span class="na">$TTL</span><span class="w"> </span><span class="sc">86400</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="na">$ORIGIN</span><span class="w"> </span><span class="sc">1</span><span class="py">.168.192.in-addr.arpa.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">@</span><span class="w">   </span><span class="k">IN</span><span class="w">  </span><span class="k">SOA</span><span class="w"> </span><span class="py">ns1.example.com. admin.example.com. </span><span class="p">(</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="sc">2024121201</span><span class="w">  </span><span class="c">; Serial</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="sc">3600</span><span class="w">        </span><span class="c">; Refresh</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="sc">1800</span><span class="w">        </span><span class="c">; Retry</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="sc">604800</span><span class="w">      </span><span class="c">; Expire</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="sc">86400</span><span class="w">       </span><span class="c">; Minimum TTL</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c">; Nameservers</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">@</span><span class="w">       </span><span class="k">IN</span><span class="w">  </span><span class="k">NS</span><span class="w">      </span><span class="py">ns1.example.com.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">@</span><span class="w">       </span><span class="k">IN</span><span class="w">  </span><span class="k">NS</span><span class="w">      </span><span class="py">ns2.example.com.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c">; PTR records</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="sc">1</span><span class="w">       </span><span class="k">IN</span><span class="w">  </span><span class="k">PTR</span><span class="w">     </span><span class="py">ns1.example.com.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="sc">2</span><span class="w">       </span><span class="k">IN</span><span class="w">  </span><span class="k">PTR</span><span class="w">     </span><span class="py">ns2.example.com.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="sc">10</span><span class="w">      </span><span class="k">IN</span><span class="w">  </span><span class="k">PTR</span><span class="w">     </span><span class="py">mail.example.com.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="sc">11</span><span class="w">      </span><span class="k">IN</span><span class="w">  </span><span class="k">PTR</span><span class="w">     </span><span class="py">mail2.example.com.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="sc">20</span><span class="w">      </span><span class="k">IN</span><span class="w">  </span><span class="k">PTR</span><span class="w">     </span><span class="py">ftp.example.com.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="sc">100</span><span class="w">     </span><span class="k">IN</span><span class="w">  </span><span class="k">PTR</span><span class="w">     </span><span class="py">server1.example.com.</span><span class="w">
</span></span></span></code></pre></div><h2 id="understanding-the-soa-record">Understanding the SOA Record <a class="anchor" data-pagefind-ignore href="#understanding-the-soa-record" aria-label="Link to this section">#</a></h2>
<p>The SOA timers control how the slave keeps its copy in sync. <code>admin.example.com.</code> is the contact address (<code>admin@example.com</code>).</p>
<table>
	<thead>
			<tr>
					<th>Field</th>
					<th>Description</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Serial</td>
					<td>Version number - increment with each change</td>
			</tr>
			<tr>
					<td>Refresh</td>
					<td>How often secondaries check for updates</td>
			</tr>
			<tr>
					<td>Retry</td>
					<td>How long to wait before retrying failed refresh</td>
			</tr>
			<tr>
					<td>Expire</td>
					<td>When secondary stops serving zone if refresh fails</td>
			</tr>
			<tr>
					<td>Minimum TTL</td>
					<td>Default negative caching TTL</td>
			</tr>
	</tbody>
</table>
<p><strong>Serial number format:</strong> use <code>YYYYMMDDNN</code>, where NN is the revision number for that day. The slave only transfers when the serial goes up.</p>
<h2 id="validate-configuration">Validate Configuration <a class="anchor" data-pagefind-ignore href="#validate-configuration" aria-label="Link to this section">#</a></h2>
<p>Check syntax before every (re)load, so a typo never reaches the running server.</p>
<ul>
<li><code>named-checkconf</code>: the configuration files.</li>
<li><code>named-checkzone &lt;zone&gt; &lt;file&gt;</code>: one zone file, including the SOA and record syntax.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check named.conf</span>
</span></span><span class="line"><span class="cl">sudo named-checkconf
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check zone files</span>
</span></span><span class="line"><span class="cl">sudo named-checkzone example.com /var/lib/bind/zones/example.com.zone
</span></span><span class="line"><span class="cl">sudo named-checkzone 1.168.192.in-addr.arpa /var/lib/bind/zones/192.168.1.rev
</span></span></code></pre></div><p>Expected output for valid zones:</p>
<pre tabindex="0"><code>zone example.com/IN: loaded serial 2024121201
OK
</code></pre><h2 id="start-and-enable-bind">Start and Enable BIND <a class="anchor" data-pagefind-ignore href="#start-and-enable-bind" aria-label="Link to this section">#</a></h2>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo systemctl <span class="nb">enable</span> --now named
</span></span><span class="line"><span class="cl">sudo systemctl status named
</span></span></code></pre></div><h2 id="testing">Testing <a class="anchor" data-pagefind-ignore href="#testing" aria-label="Link to this section">#</a></h2>
<p>Query the server directly with <code>dig @localhost</code>. Answers for your zones should carry the <code>aa</code> (authoritative answer) flag. The AXFR from localhost should fail: only the slave is allowed to transfer.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Query the server directly</span>
</span></span><span class="line"><span class="cl">dig @localhost example.com
</span></span><span class="line"><span class="cl">dig @localhost example.com NS
</span></span><span class="line"><span class="cl">dig @localhost example.com MX
</span></span><span class="line"><span class="cl">dig @localhost www.example.com A
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test reverse lookup</span>
</span></span><span class="line"><span class="cl">dig @localhost -x 192.168.1.10
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check SOA record</span>
</span></span><span class="line"><span class="cl">dig @localhost example.com SOA
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test AXFR (zone transfer) - should fail from unauthorized IPs</span>
</span></span><span class="line"><span class="cl">dig @localhost example.com AXFR
</span></span></code></pre></div><h2 id="reload-without-restart">Reload Without Restart <a class="anchor" data-pagefind-ignore href="#reload-without-restart" aria-label="Link to this section">#</a></h2>
<p>After a zone change, <code>rndc reload</code> loads it without restarting the process. Reload a single zone to keep the change contained.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Reload all zones</span>
</span></span><span class="line"><span class="cl">sudo rndc reload
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Reload specific zone</span>
</span></span><span class="line"><span class="cl">sudo rndc reload example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check server status</span>
</span></span><span class="line"><span class="cl">sudo rndc status
</span></span></code></pre></div><p><strong>Important:</strong> always increment the serial number when modifying zone files. Without it, the slave keeps serving the old data.</p>
<h2 id="logging-configuration">Logging Configuration <a class="anchor" data-pagefind-ignore href="#logging-configuration" aria-label="Link to this section">#</a></h2>
<p>Separate log files make transfer problems easy to find. Add this to the configuration:</p>
<ul>
<li><code>channel default_log</code>: general server messages.</li>
<li><code>channel xfer_log</code>: zone transfers in and out, plus NOTIFY messages; the first place to look when the slave is out of sync.</li>
<li><code>versions 3 size 5m</code>: rotate at 5 MB, keep three old files.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bind" data-lang="bind"><span class="line"><span class="cl"><span class="nc">logging</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">channel</span><span class="w"> </span><span class="err">default_log</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">file</span><span class="w"> </span><span class="err">&#34;/var/log/named/</span><span class="nc">default.log</span><span class="err">&#34;</span><span class="w"> </span><span class="err">versions</span><span class="w"> </span><span class="sc">3</span><span class="w"> </span><span class="err">size</span><span class="w"> </span><span class="sc">5m</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">severity</span><span class="w"> </span><span class="err">info</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">print-time</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">print-severity</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">print-category</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">channel</span><span class="w"> </span><span class="err">xfer_log</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">file</span><span class="w"> </span><span class="err">&#34;/var/log/named/</span><span class="nc">xfer.log</span><span class="err">&#34;</span><span class="w"> </span><span class="err">versions</span><span class="w"> </span><span class="sc">3</span><span class="w"> </span><span class="err">size</span><span class="w"> </span><span class="sc">5m</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">severity</span><span class="w"> </span><span class="err">info</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">print-time</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">category</span><span class="w"> </span><span class="err">default</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">default_log</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">category</span><span class="w"> </span><span class="err">xfer-in</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">xfer_log</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">category</span><span class="w"> </span><span class="err">xfer-out</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">xfer_log</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">category</span><span class="w"> </span><span class="err">notify</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">xfer_log</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span></code></pre></div><p>Create the log directory before restarting BIND. If it is missing, <code>named-checkconf</code> still passes but <code>named</code> refuses to start (<code>configuring logging: file not found</code>):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo mkdir -p /var/log/named
</span></span><span class="line"><span class="cl">sudo chown bind:bind /var/log/named    <span class="c1"># RHEL: named:named</span>
</span></span></code></pre></div><h2 id="firewall-configuration">Firewall Configuration <a class="anchor" data-pagefind-ignore href="#firewall-configuration" aria-label="Link to this section">#</a></h2>
<p>DNS uses UDP for normal queries and TCP for large answers and zone transfers, so open both.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># UFW</span>
</span></span><span class="line"><span class="cl">sudo ufw allow 53/tcp
</span></span><span class="line"><span class="cl">sudo ufw allow 53/udp
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># firewalld</span>
</span></span><span class="line"><span class="cl">sudo firewall-cmd --permanent --add-service<span class="o">=</span>dns
</span></span><span class="line"><span class="cl">sudo firewall-cmd --reload
</span></span></code></pre></div><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Likely cause / fix</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Slave still serves old records</td>
					<td>Serial not incremented on the master; bump it and <code>rndc reload</code></td>
			</tr>
			<tr>
					<td>Zone does not load</td>
					<td>Syntax error; run <code>named-checkzone</code> and check the log</td>
			</tr>
			<tr>
					<td><code>named</code> does not start after adding logging</td>
					<td><code>/var/log/named</code> missing or not owned by the BIND user</td>
			</tr>
			<tr>
					<td>Transfer refused</td>
					<td>Slave IP missing from <code>allow-transfer</code>; check <code>xfer.log</code></td>
			</tr>
			<tr>
					<td>Remote clients time out</td>
					<td>Port 53 closed for UDP or TCP in the firewall</td>
			</tr>
	</tbody>
</table>
<h2 id="best-practices">Best Practices <a class="anchor" data-pagefind-ignore href="#best-practices" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Run at least two authoritative servers</strong> for redundancy.</li>
<li><strong>Use TSIG keys</strong> to authenticate zone transfers between master and slave (see the <a href="https://blog.bsdserver.nl/how-to-configure-bind-rndc-and-tsig-keys-for-remote-dns-management/">rndc and TSIG post</a>).</li>
<li><strong>Implement DNSSEC</strong> for cryptographic validation.</li>
<li><strong>Monitor zone serial numbers</strong> to ensure slaves are synchronized.</li>
<li><strong>Use date-based serial numbers</strong>.</li>
<li><strong>Set appropriate TTLs</strong>: lower for frequently changing records.</li>
<li><strong>Keep logs</strong> for troubleshooting and security auditing.</li>
</ul>
<h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub:
<a href="https://github.com/pderuiter/blog-bind-authoritative" rel="noopener">pderuiter/blog-bind-authoritative</a>. It creates two Ubuntu 24.04 VMs on Proxmox and configures the master and slave from this post, with the zones, transfer restrictions, rate limiting and logging; fill in <code>terraform.tfvars</code>, run <code>terraform apply</code>, then <code>ansible-playbook site.yml</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>You now have an authoritative-only master and slave. Key points:</p>
<ul>
<li>Authoritative servers only answer for their configured zones; recursion stays off.</li>
<li>The master holds the files, the slave copies them by zone transfer.</li>
<li>Always increment the serial when updating a zone, and validate before reloading.</li>
</ul>
<p>In the next posts, we&rsquo;ll cover securing zone transfers with TSIG keys, implementing DNSSEC, and integrating with dynamic DNS updates.</p>
]]></content:encoded></item><item><title>How to Configure BIND RNDC and TSIG Keys for Remote DNS Management</title><link>https://blog.bsdserver.nl/how-to-configure-bind-rndc-and-tsig-keys-for-remote-dns-management/</link><guid isPermaLink="false">693b6bae79eb54000160a54e</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:11:10 +0000</pubDate><description>RNDC (Remote Name Daemon Control) is the administrative tool for managing BIND DNS servers.</description><category>BIND</category><category>DNS</category><category>rndc</category><category>TSIG</category><category>Security</category><category>Linux</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/bind-rndc-tsig.png" medium="image"/><content:encoded><![CDATA[<p>RNDC (Remote Name Daemon Control) is the administrative tool for managing BIND DNS servers. It reloads zones, flushes caches and shows statistics without restarting the service.</p>
<p>This post sets up RNDC keys for local and remote administration, a read-only channel for monitoring, and TSIG keys that authenticate zone transfers between master and slave.</p>
<h2 id="why-rndc-and-tsig">Why RNDC and TSIG? <a class="anchor" data-pagefind-ignore href="#why-rndc-and-tsig" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>No restarts</strong>: reload a zone or the configuration while <code>named</code> keeps answering.</li>
<li><strong>Remote control</strong>: manage several DNS servers from one admin workstation.</li>
<li><strong>Authenticated</strong>: every command and every zone transfer is signed with a shared secret.</li>
<li><strong>Least privilege</strong>: separate keys and read-only channels for monitoring.</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> on every BIND server: local RNDC is the normal way to reload zones. Add remote access and TSIG when you run more than one server.</li>
<li><strong>Skip</strong> remote RNDC if you manage servers only over SSH; keep the local channel.</li>
</ul>
<h2 id="how-it-works">How It Works <a class="anchor" data-pagefind-ignore href="#how-it-works" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Piece</th>
					<th>Protects</th>
					<th>Where</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>RNDC key + <code>controls</code></td>
					<td>Admin commands to <code>named</code></td>
					<td>TCP port 953 (by default)</td>
			</tr>
			<tr>
					<td><code>rndc.conf</code></td>
					<td>Which key and server the <code>rndc</code> client uses</td>
					<td>Admin workstation or the server itself</td>
			</tr>
			<tr>
					<td>TSIG transfer key</td>
					<td>Zone transfers and NOTIFY between master and slave</td>
					<td>Port 53, inside the DNS messages</td>
			</tr>
	</tbody>
</table>
<p>Both use the same mechanism: a shared HMAC secret. <strong>RNDC</strong> signs each command with it; <strong>TSIG</strong> (Transaction Signature) signs DNS messages with it. A message without a valid signature is rejected.</p>
<p>The flow for a remote reload: <code>rndc -s dns1 reload</code> → the client signs the command with the key from <code>rndc.conf</code> → <code>named</code> checks the source IP against <code>allow</code> and the signature against <code>keys</code> → runs the command.</p>
<h2 id="generating-rndc-keys">Generating RNDC Keys <a class="anchor" data-pagefind-ignore href="#generating-rndc-keys" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Command</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>rndc-confgen -a</code></td>
					<td>Local administration only; writes a key file <code>named</code> reads automatically</td>
			</tr>
			<tr>
					<td><code>rndc-confgen</code></td>
					<td>Remote administration; prints a full <code>rndc.conf</code> and the matching <code>named.conf</code> snippet</td>
			</tr>
			<tr>
					<td><code>tsig-keygen</code></td>
					<td>Zone transfer and dynamic update keys (see below)</td>
			</tr>
	</tbody>
</table>
<h3 id="automatic-generation">Automatic Generation <a class="anchor" data-pagefind-ignore href="#automatic-generation" aria-label="Link to this section">#</a></h3>
<p>The simplest way to set up RNDC is using <code>rndc-confgen</code> with the <code>-a</code> flag:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">rndc-confgen -a
</span></span></code></pre></div><p>This creates <code>/etc/rndc.key</code> (RHEL) or <code>/etc/bind/rndc.key</code> (Debian/Ubuntu) with a randomly generated key:</p>
<pre tabindex="0"><code>key &#34;rndc-key&#34; {
    algorithm hmac-sha256;
    secret &#34;base64-encoded-secret&#34;;
};
</code></pre><p>BIND automatically includes this file, so no additional configuration is needed for local administration. However, <code>rndc-confgen -a</code> creates the file mode <code>0600</code> and owned by root, so <code>named</code>, which runs as <code>named</code> (RHEL) or <code>bind</code> (Debian/Ubuntu), cannot read it. The log then shows <code>open: /etc/rndc.key: permission denied</code> and <code>rndc</code> fails with <code>connection to remote host closed</code>. Either pass the daemon user with <code>-u</code>, or fix ownership afterwards and restart <code>named</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">rndc-confgen -a -u named          <span class="c1"># Debian/Ubuntu: -u bind</span>
</span></span><span class="line"><span class="cl"><span class="c1"># or</span>
</span></span><span class="line"><span class="cl">chown root:named /etc/rndc.key <span class="o">&amp;&amp;</span> chmod <span class="m">640</span> /etc/rndc.key
</span></span></code></pre></div><h3 id="manual-generation">Manual Generation <a class="anchor" data-pagefind-ignore href="#manual-generation" aria-label="Link to this section">#</a></h3>
<p>For remote administration you need the key on both sides. Without <code>-a</code>, <code>rndc-confgen</code> prints both halves:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">rndc-confgen
</span></span></code></pre></div><p>This outputs both the <code>rndc.conf</code> content and the corresponding <code>named.conf</code> additions:</p>
<pre tabindex="0"><code># Start of rndc.conf
key &#34;rndc-key&#34; {
    algorithm hmac-sha256;
    secret &#34;wImDGsj5MxtGQl1nL0V2V/eTlpKs3VdS4nKxEhJVyKY=&#34;;
};

options {
    default-key &#34;rndc-key&#34;;
    default-server 127.0.0.1;
    default-port 953;
};
# End of rndc.conf

# Use with the following in named.conf, adjusting the allow list as needed:
# key &#34;rndc-key&#34; {
#     algorithm hmac-sha256;
#     secret &#34;wImDGsj5MxtGQl1nL0V2V/eTlpKs3VdS4nKxEhJVyKY=&#34;;
# };
#
# controls {
#     inet 127.0.0.1 port 953
#         allow { 127.0.0.1; } keys { &#34;rndc-key&#34;; };
# };
# End of named.conf
</code></pre><h3 id="specifying-key-algorithm">Specifying Key Algorithm <a class="anchor" data-pagefind-ignore href="#specifying-key-algorithm" aria-label="Link to this section">#</a></h3>
<p>BIND supports several HMAC algorithms. <code>-A</code> picks the algorithm and <code>-k</code> the key name; both sides must use the same.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># SHA-256 (recommended)</span>
</span></span><span class="line"><span class="cl">rndc-confgen -a -A hmac-sha256
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># SHA-512 (strongest)</span>
</span></span><span class="line"><span class="cl">rndc-confgen -a -A hmac-sha512
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Custom key name</span>
</span></span><span class="line"><span class="cl">rndc-confgen -a -k my-admin-key
</span></span></code></pre></div><h2 id="configuring-namedconf">Configuring named.conf <a class="anchor" data-pagefind-ignore href="#configuring-namedconf" aria-label="Link to this section">#</a></h2>
<h3 id="the-controls-statement">The Controls Statement <a class="anchor" data-pagefind-ignore href="#the-controls-statement" aria-label="Link to this section">#</a></h3>
<p>The <code>controls</code> statement decides where <code>named</code> listens for RNDC, who may connect and with which key. Without a <code>controls</code> statement, <code>named</code> listens on localhost and uses <code>rndc.key</code>.</p>
<pre tabindex="0"><code>controls {
    inet 127.0.0.1 port 953
        allow { 127.0.0.1; } keys { &#34;rndc-key&#34;; };
};
</code></pre><ul>
<li><code>inet 127.0.0.1</code>: listen address.</li>
<li><code>port 953</code>: TCP port (953 is the default).</li>
<li><code>allow { 127.0.0.1; }</code>: IP addresses allowed to connect.</li>
<li><code>keys { &quot;rndc-key&quot;; }</code>: keys accepted for authentication. A client needs both an allowed IP and a valid key.</li>
</ul>
<h3 id="enabling-remote-administration">Enabling Remote Administration <a class="anchor" data-pagefind-ignore href="#enabling-remote-administration" aria-label="Link to this section">#</a></h3>
<p>To manage BIND from remote hosts, add a second <code>inet</code> line on the server&rsquo;s LAN address. The <code>admin-hosts</code> ACL limits it to the admin network; the localhost channel stays for local use.</p>
<pre tabindex="0"><code>key &#34;rndc-key&#34; {
    algorithm hmac-sha256;
    secret &#34;wImDGsj5MxtGQl1nL0V2V/eTlpKs3VdS4nKxEhJVyKY=&#34;;
};

acl &#34;admin-hosts&#34; {
    127.0.0.1;
    192.168.1.10;        # Admin workstation
    192.168.1.0/24;      # Admin network
};

controls {
    inet 127.0.0.1 port 953
        allow { 127.0.0.1; } keys { &#34;rndc-key&#34;; };
    inet 192.168.1.1 port 953
        allow { admin-hosts; } keys { &#34;rndc-key&#34;; };
};
</code></pre><h3 id="multiple-keys-for-different-access-levels">Multiple Keys for Different Access Levels <a class="anchor" data-pagefind-ignore href="#multiple-keys-for-different-access-levels" aria-label="Link to this section">#</a></h3>
<p>Separate keys let you revoke one system without touching the others. Every key listed on a control channel gets full control (including <code>rndc stop</code>) unless that channel is marked <code>read-only yes</code>. One <code>inet</code> address/port has only one read-only setting, so give the monitoring key its own port:</p>
<table>
	<thead>
			<tr>
					<th>Channel</th>
					<th>Key</th>
					<th>Access</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>127.0.0.1:953</code></td>
					<td><code>admin-key</code></td>
					<td>Full, local</td>
			</tr>
			<tr>
					<td><code>192.168.1.1:953</code></td>
					<td><code>admin-key</code></td>
					<td>Full, from the admin network</td>
			</tr>
			<tr>
					<td><code>192.168.1.1:954</code></td>
					<td><code>monitoring-key</code></td>
					<td>Read-only (status, stats)</td>
			</tr>
	</tbody>
</table>
<pre tabindex="0"><code>key &#34;admin-key&#34; {
    algorithm hmac-sha256;
    secret &#34;first-secret-here&#34;;
};

key &#34;monitoring-key&#34; {
    algorithm hmac-sha256;
    secret &#34;second-secret-here&#34;;
};

key &#34;secondary-ns-key&#34; {
    algorithm hmac-sha256;
    secret &#34;third-secret-here&#34;;
};

controls {
    inet 127.0.0.1 port 953
        allow { 127.0.0.1; } keys { &#34;admin-key&#34;; };
    inet 192.168.1.1 port 953
        allow { 192.168.1.0/24; } keys { &#34;admin-key&#34;; };
    // Monitoring: status/stats only, write commands are rejected
    inet 192.168.1.1 port 954
        allow { 192.168.1.0/24; } keys { &#34;monitoring-key&#34;; } read-only yes;
};
</code></pre><p>The monitoring system then connects with <code>rndc -p 954 ... status</code>.</p>
<h2 id="configuring-rndcconf">Configuring rndc.conf <a class="anchor" data-pagefind-ignore href="#configuring-rndcconf" aria-label="Link to this section">#</a></h2>
<p><code>rndc.conf</code> is the client side: which key to sign with and which server to talk to. It lives in <code>/etc/rndc.conf</code> (RHEL) or <code>/etc/bind/rndc.conf</code> (Debian/Ubuntu; <code>rndc</code> ignores <code>/etc/rndc.conf</code> there). When it exists it takes precedence over <code>rndc.key</code>.</p>
<ul>
<li><code>options</code>: the defaults when you run <code>rndc</code> without <code>-s</code>.</li>
<li><code>server</code> blocks: per-server key and port, selected with <code>rndc -s &lt;name&gt;</code>.</li>
</ul>
<pre tabindex="0"><code>key &#34;rndc-key&#34; {
    algorithm hmac-sha256;
    secret &#34;wImDGsj5MxtGQl1nL0V2V/eTlpKs3VdS4nKxEhJVyKY=&#34;;
};

options {
    default-key &#34;rndc-key&#34;;
    default-server 127.0.0.1;
    default-port 953;
};

# Define additional servers
server dns1.example.com {
    key &#34;rndc-key&#34;;
    port 953;
};

server dns2.example.com {
    key &#34;rndc-key&#34;;
    port 953;
};
</code></pre><p>With multiple servers defined, specify which to manage:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">rndc -s dns1.example.com reload
</span></span><span class="line"><span class="cl">rndc -s dns2.example.com reload
</span></span></code></pre></div><h2 id="tsig-keys-for-zone-transfers">TSIG Keys for Zone Transfers <a class="anchor" data-pagefind-ignore href="#tsig-keys-for-zone-transfers" aria-label="Link to this section">#</a></h2>
<p>Without TSIG, a zone transfer is only protected by the IP in <code>allow-transfer</code>. A TSIG key proves that the slave is who it says it is, and that the zone data was not altered on the way.</p>
<table>
	<thead>
			<tr>
					<th>Server</th>
					<th>IP</th>
					<th>Role</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Master</td>
					<td><code>192.168.1.2</code></td>
					<td>Holds the zone file, allows transfers signed with <code>transfer-key</code></td>
			</tr>
			<tr>
					<td>Slave</td>
					<td><code>192.168.1.3</code></td>
					<td>Transfers the zone, signing its requests with <code>transfer-key</code></td>
			</tr>
	</tbody>
</table>
<h3 id="generating-a-transfer-key">Generating a Transfer Key <a class="anchor" data-pagefind-ignore href="#generating-a-transfer-key" aria-label="Link to this section">#</a></h3>
<p><code>tsig-keygen</code> prints a ready-to-include <code>key</code> block. Generate it once and copy the same block to both servers.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">tsig-keygen -a hmac-sha256 transfer-key
</span></span></code></pre></div><p>Output:</p>
<pre tabindex="0"><code>key &#34;transfer-key&#34; {
    algorithm hmac-sha256;
    secret &#34;generated-secret&#34;;
};
</code></pre><h3 id="master-server-configuration">Master Server Configuration <a class="anchor" data-pagefind-ignore href="#master-server-configuration" aria-label="Link to this section">#</a></h3>
<ul>
<li><code>server 192.168.1.3 { keys ... }</code>: sign everything sent to the slave, such as NOTIFY messages, with the key.</li>
<li><code>allow-transfer { key &quot;transfer-key&quot;; }</code>: only requests signed with this key may transfer the zone.</li>
<li><code>also-notify</code>: tell the slave about changes straight away.</li>
</ul>
<pre tabindex="0"><code>key &#34;transfer-key&#34; {
    algorithm hmac-sha256;
    secret &#34;generated-secret&#34;;
};

server 192.168.1.3 {
    keys { &#34;transfer-key&#34;; };
};

zone &#34;example.com&#34; {
    type primary;
    file &#34;/var/named/zones/example.com.zone&#34;;
    allow-transfer { key &#34;transfer-key&#34;; };
    also-notify { 192.168.1.3; };
};
</code></pre><p>The zone and key paths in this section and in <a href="#avoid-storing-keys-in-main-config">Avoid Storing Keys in Main Config</a> are the RHEL ones. On Debian/Ubuntu, AppArmor only lets <code>named</code> read <code>/etc/bind</code> and write <code>/var/lib/bind</code> and <code>/var/cache/bind</code>, so use <code>/var/lib/bind/zones/</code> instead of <code>/var/named/zones/</code> and <code>/etc/bind/keys/</code> instead of <code>/etc/named/keys/</code> (or add a local AppArmor override in <code>/etc/apparmor.d/local/usr.sbin.named</code>).</p>
<h3 id="slave-server-configuration">Slave Server Configuration <a class="anchor" data-pagefind-ignore href="#slave-server-configuration" aria-label="Link to this section">#</a></h3>
<p>The mirror image: the <code>server</code> block makes the slave sign its transfer requests to the master with the same key.</p>
<pre tabindex="0"><code>key &#34;transfer-key&#34; {
    algorithm hmac-sha256;
    secret &#34;generated-secret&#34;;
};

server 192.168.1.2 {
    keys { &#34;transfer-key&#34;; };
};

zone &#34;example.com&#34; {
    type secondary;
    file &#34;/var/named/zones/example.com.zone&#34;;
    primaries { 192.168.1.2; };
};
</code></pre><h2 id="essential-rndc-commands">Essential RNDC Commands <a class="anchor" data-pagefind-ignore href="#essential-rndc-commands" aria-label="Link to this section">#</a></h2>
<p>The commands you will use most, grouped by job.</p>
<h3 id="zone-management">Zone Management <a class="anchor" data-pagefind-ignore href="#zone-management" aria-label="Link to this section">#</a></h3>
<ul>
<li><code>reload</code>: re-read zone files on the master after an edit.</li>
<li><code>refresh</code> / <code>retransfer</code>: on a slave; check the serial now, or force a full transfer regardless of the serial.</li>
<li><code>freeze</code> / <code>thaw</code>: pause dynamic updates so you can edit a dynamic zone&rsquo;s file by hand.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Reload all zones</span>
</span></span><span class="line"><span class="cl">rndc reload
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Reload specific zone</span>
</span></span><span class="line"><span class="cl">rndc reload example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Reload zone in specific view</span>
</span></span><span class="line"><span class="cl">rndc reload example.com IN internal
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Force zone refresh (secondary)</span>
</span></span><span class="line"><span class="cl">rndc refresh example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Re-transfer zone (secondary)</span>
</span></span><span class="line"><span class="cl">rndc retransfer example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Sign zone with DNSSEC keys (zones with a dnssec-policy only)</span>
</span></span><span class="line"><span class="cl">rndc sign example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Freeze zone for manual editing (dynamic zones only)</span>
</span></span><span class="line"><span class="cl">rndc freeze example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Thaw zone after editing</span>
</span></span><span class="line"><span class="cl">rndc thaw example.com
</span></span></code></pre></div><h3 id="cache-management">Cache Management <a class="anchor" data-pagefind-ignore href="#cache-management" aria-label="Link to this section">#</a></h3>
<p>On a resolver, flush a name after a record changed upstream and clients keep getting the old answer. <code>flushtree</code> also removes everything below the name.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Flush entire cache</span>
</span></span><span class="line"><span class="cl">rndc flush
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Flush specific name from cache</span>
</span></span><span class="line"><span class="cl">rndc flushname example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Flush entire domain tree</span>
</span></span><span class="line"><span class="cl">rndc flushtree example.com
</span></span></code></pre></div><h3 id="server-control">Server Control <a class="anchor" data-pagefind-ignore href="#server-control" aria-label="Link to this section">#</a></h3>
<p><code>reconfig</code> only picks up configuration changes and new zones; use it when you have not edited existing zone files. <code>stop</code> saves pending changes first, <code>halt</code> does not.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Reload configuration (not zones)</span>
</span></span><span class="line"><span class="cl">rndc reconfig
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check server status</span>
</span></span><span class="line"><span class="cl">rndc status
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Stop the server</span>
</span></span><span class="line"><span class="cl">rndc stop
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Halt immediately</span>
</span></span><span class="line"><span class="cl">rndc halt
</span></span></code></pre></div><h3 id="logging-and-debugging">Logging and Debugging <a class="anchor" data-pagefind-ignore href="#logging-and-debugging" aria-label="Link to this section">#</a></h3>
<p><code>dumpdb</code> and <code>stats</code> write to files in the server&rsquo;s working directory. <code>trace</code> raises the debug level by one per call.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Dump cache to file</span>
</span></span><span class="line"><span class="cl">rndc dumpdb -cache
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Dump zones to file</span>
</span></span><span class="line"><span class="cl">rndc dumpdb -zones
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Write server statistics</span>
</span></span><span class="line"><span class="cl">rndc stats
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Increment debug level</span>
</span></span><span class="line"><span class="cl">rndc trace
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Disable debugging</span>
</span></span><span class="line"><span class="cl">rndc notrace
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Toggle query logging</span>
</span></span><span class="line"><span class="cl">rndc querylog
</span></span></code></pre></div><h2 id="security-best-practices">Security Best Practices <a class="anchor" data-pagefind-ignore href="#security-best-practices" aria-label="Link to this section">#</a></h2>
<h3 id="key-file-permissions">Key File Permissions <a class="anchor" data-pagefind-ignore href="#key-file-permissions" aria-label="Link to this section">#</a></h3>
<p>The key files hold the secrets: readable by root and the BIND group only.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Restrict key file access</span>
</span></span><span class="line"><span class="cl">chmod <span class="m">640</span> /etc/rndc.key
</span></span><span class="line"><span class="cl">chown root:named /etc/rndc.key
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">chmod <span class="m">640</span> /etc/rndc.conf
</span></span><span class="line"><span class="cl">chown root:named /etc/rndc.conf
</span></span></code></pre></div><p>On Debian/Ubuntu the files are <code>/etc/bind/rndc.key</code> and <code>/etc/bind/rndc.conf</code>, and the group is <code>bind</code> (there is no <code>named</code> group).</p>
<h3 id="separate-keys-per-purpose">Separate Keys per Purpose <a class="anchor" data-pagefind-ignore href="#separate-keys-per-purpose" aria-label="Link to this section">#</a></h3>
<p>A leaked transfer key should not let anyone stop your server. Use different keys for different functions:</p>
<pre tabindex="0"><code># Administrative key - full access
key &#34;admin-key&#34; {
    algorithm hmac-sha512;
    secret &#34;admin-secret&#34;;
};

# Transfer key - zone transfers only
key &#34;xfr-key&#34; {
    algorithm hmac-sha256;
    secret &#34;transfer-secret&#34;;
};

# Update key - dynamic updates only
key &#34;update-key&#34; {
    algorithm hmac-sha256;
    secret &#34;update-secret&#34;;
};
</code></pre><h3 id="firewall-rules">Firewall Rules <a class="anchor" data-pagefind-ignore href="#firewall-rules" aria-label="Link to this section">#</a></h3>
<p>Restrict the RNDC port to the admin network, as a second layer behind <code>allow</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Allow RNDC only from admin network</span>
</span></span><span class="line"><span class="cl">iptables -A INPUT -p tcp --dport <span class="m">953</span> -s 192.168.1.0/24 -j ACCEPT
</span></span><span class="line"><span class="cl">iptables -A INPUT -p tcp --dport <span class="m">953</span> -j DROP
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Or with firewalld</span>
</span></span><span class="line"><span class="cl">firewall-cmd --permanent --add-rich-rule<span class="o">=</span><span class="s1">&#39;rule family=ipv4 source address=192.168.1.0/24 port port=953 protocol=tcp accept&#39;</span>
</span></span></code></pre></div><h3 id="avoid-storing-keys-in-main-config">Avoid Storing Keys in Main Config <a class="anchor" data-pagefind-ignore href="#avoid-storing-keys-in-main-config" aria-label="Link to this section">#</a></h3>
<p>Keep secrets in separate files and include them, so you can share <code>named.conf</code> without leaking keys:</p>
<pre tabindex="0"><code>include &#34;/etc/named/keys/rndc.key&#34;;
include &#34;/etc/named/keys/transfer.key&#34;;
</code></pre><p>This keeps sensitive data separate and simplifies key rotation.</p>
<h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Likely cause</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>connection refused</code></td>
					<td><code>named</code> not running, or no <code>controls</code> channel on that address/port</td>
			</tr>
			<tr>
					<td><code>connection to remote host closed</code></td>
					<td>Wrong key, wrong source IP, or <code>named</code> cannot read <code>rndc.key</code></td>
			</tr>
			<tr>
					<td><code>decode base64 secret</code></td>
					<td>Secret in <code>rndc.conf</code> is not valid base64</td>
			</tr>
			<tr>
					<td>Permission errors</td>
					<td>File ownership, SELinux or AppArmor</td>
			</tr>
	</tbody>
</table>
<h3 id="connection-refused">Connection Refused <a class="anchor" data-pagefind-ignore href="#connection-refused" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">rndc status
</span></span><span class="line"><span class="cl"><span class="c1"># rndc: connect failed: 127.0.0.1#953: connection refused</span>
</span></span></code></pre></div><p>Check that <code>named</code> is running and the controls statement is configured:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">systemctl status named
</span></span><span class="line"><span class="cl">named-checkconf /etc/named.conf
</span></span><span class="line"><span class="cl">ss -tlnp <span class="p">|</span> grep <span class="m">953</span>
</span></span></code></pre></div><h3 id="authentication-failure">Authentication Failure <a class="anchor" data-pagefind-ignore href="#authentication-failure" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">rndc status
</span></span><span class="line"><span class="cl"><span class="c1"># rndc: connection to remote host closed.</span>
</span></span><span class="line"><span class="cl"><span class="c1"># * This may indicate that the</span>
</span></span><span class="line"><span class="cl"><span class="c1"># * remote server is using an older</span>
</span></span><span class="line"><span class="cl"><span class="c1"># * version of the command protocol,</span>
</span></span><span class="line"><span class="cl"><span class="c1"># * this host is not authorized to connect,</span>
</span></span><span class="line"><span class="cl"><span class="c1"># * the clocks are not synchronized,</span>
</span></span><span class="line"><span class="cl"><span class="c1"># * the key signing algorithm is incorrect</span>
</span></span><span class="line"><span class="cl"><span class="c1"># * or the key is invalid.</span>
</span></span></code></pre></div><p>On the server, <code>named</code> logs <code>invalid command from 127.0.0.1#...: bad auth</code>. A secret that is not valid base64 fails earlier, on the client: <code>rndc: decode base64 secret: bad base64 encoding</code>.</p>
<p>Verify keys match between <code>rndc.conf</code> and the key <code>named</code> uses (<code>named.conf</code>, or <code>rndc.key</code> when there is no <code>controls</code> statement):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Compare secrets</span>
</span></span><span class="line"><span class="cl">grep secret /etc/rndc.conf
</span></span><span class="line"><span class="cl">grep -A2 <span class="s1">&#39;key &#34;rndc-key&#34;&#39;</span> /etc/named.conf
</span></span><span class="line"><span class="cl">grep secret /etc/rndc.key
</span></span></code></pre></div><h3 id="permission-denied">Permission Denied <a class="anchor" data-pagefind-ignore href="#permission-denied" aria-label="Link to this section">#</a></h3>
<p>Check file permissions and SELinux:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">ls -la /etc/rndc.key
</span></span><span class="line"><span class="cl">getenforce
</span></span><span class="line"><span class="cl">ausearch -m AVC -ts recent <span class="p">|</span> grep named
</span></span></code></pre></div><h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub:
<a href="https://github.com/pderuiter/blog-bind-rndc-tsig" rel="noopener">pderuiter/blog-bind-rndc-tsig</a>. It creates a master, a slave and an admin workstation, sets up the admin and read-only monitoring control channels, the TSIG-signed zone transfer and the workstation&rsquo;s <code>rndc.conf</code>; put your keys in an ansible-vault file, then run <code>terraform apply</code> and <code>ansible-playbook site.yml</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>RNDC and TSIG keys make DNS administration safe to do remotely. Use HMAC-SHA256 or HMAC-SHA512, separate keys per purpose, a read-only channel for monitoring, and restrict network access to the RNDC port.</p>
<p>The next post in this series will cover zone security, including views, ACLs, and query restrictions to protect your DNS infrastructure from abuse.</p>
]]></content:encoded></item><item><title>BIND Zone Security: Views, ACLs, and Query Restrictions</title><link>https://blog.bsdserver.nl/bind-zone-security-views-acls-and-query-restrictions/</link><guid isPermaLink="false">693b6bf979eb54000160a55c</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:12:25 +0000</pubDate><description>A properly secured DNS server is critical infrastructure.</description><category>BIND</category><category>DNS</category><category>Security</category><category>ACLs</category><category>Linux</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/bind-zone-security.png" medium="image"/><content:encoded><![CDATA[<p>A properly secured DNS server is critical infrastructure. An open resolver can be abused for DNS amplification attacks, leak internal network information, or serve as a reconnaissance tool for attackers.</p>
<p>This guide covers BIND&rsquo;s security features: Access Control Lists (ACLs), query and transfer restrictions, views for split-horizon DNS, rate limiting and security logging. It ends with one complete configuration that combines them.</p>
<h2 id="understanding-the-threat-model">Understanding the Threat Model <a class="anchor" data-pagefind-ignore href="#understanding-the-threat-model" aria-label="Link to this section">#</a></h2>
<p>Each threat has a matching BIND feature:</p>
<table>
	<thead>
			<tr>
					<th>Threat</th>
					<th>What happens</th>
					<th>Defence in this post</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Open resolver abuse</td>
					<td>Attackers use your server to amplify DDoS attacks</td>
					<td><code>allow-recursion</code>, rate limiting</td>
			</tr>
			<tr>
					<td>Information disclosure</td>
					<td>Internal hostnames and IPs leak to the internet</td>
					<td>Views, per-zone <code>allow-query</code></td>
			</tr>
			<tr>
					<td>Cache poisoning</td>
					<td>Malicious records injected into resolver caches</td>
					<td>Restricted recursion, DNSSEC validation</td>
			</tr>
			<tr>
					<td>Zone transfer exposure</td>
					<td>Unauthorized parties download your entire zone</td>
					<td><code>allow-transfer</code>, TSIG</td>
			</tr>
			<tr>
					<td>Resource exhaustion</td>
					<td>Query floods consume server resources</td>
					<td>Rate limiting, minimal responses</td>
			</tr>
	</tbody>
</table>
<h3 id="when-to-use-what">When to use what <a class="anchor" data-pagefind-ignore href="#when-to-use-what" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Every server</strong>: ACLs, restricted transfers, hidden version, rate limiting.</li>
<li><strong>Resolvers</strong>: restrict recursion and cache access to your own networks.</li>
<li><strong>Views</strong>: only when internal and external clients must get different answers for the same zone.</li>
</ul>
<h2 id="access-control-lists-acls">Access Control Lists (ACLs) <a class="anchor" data-pagefind-ignore href="#access-control-lists-acls" aria-label="Link to this section">#</a></h2>
<p>ACLs define groups of IP addresses that can be referenced throughout your configuration. Define them once, use them everywhere: changing a network then means editing one list.</p>
<h3 id="basic-acl-syntax">Basic ACL Syntax <a class="anchor" data-pagefind-ignore href="#basic-acl-syntax" aria-label="Link to this section">#</a></h3>
<p>Name each ACL after the role of the clients, so the options that use it read clearly (<code>allow-transfer { secondary-servers; }</code>).</p>
<pre tabindex="0"><code>acl &#34;trusted&#34; {
    localhost;
    localnets;
    192.168.0.0/16;
    10.0.0.0/8;
};

acl &#34;internal-networks&#34; {
    192.168.1.0/24;
    192.168.2.0/24;
    172.16.0.0/12;
};

acl &#34;secondary-servers&#34; {
    192.168.1.10;
    192.168.1.11;
};
</code></pre><h3 id="built-in-acl-keywords">Built-in ACL Keywords <a class="anchor" data-pagefind-ignore href="#built-in-acl-keywords" aria-label="Link to this section">#</a></h3>
<p>BIND provides several predefined ACLs:</p>
<table>
	<thead>
			<tr>
					<th>Keyword</th>
					<th>Matches</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>any</code></td>
					<td>All hosts</td>
			</tr>
			<tr>
					<td><code>none</code></td>
					<td>No hosts</td>
			</tr>
			<tr>
					<td><code>localhost</code></td>
					<td>IP addresses of all local interfaces</td>
			</tr>
			<tr>
					<td><code>localnets</code></td>
					<td>Networks directly connected to local interfaces</td>
			</tr>
	</tbody>
</table>
<h3 id="negation-in-acls">Negation in ACLs <a class="anchor" data-pagefind-ignore href="#negation-in-acls" aria-label="Link to this section">#</a></h3>
<p>Use <code>!</code> to exclude addresses. This ACL matches everyone outside the private ranges:</p>
<pre tabindex="0"><code>acl &#34;external-only&#34; {
    !10.0.0.0/8;
    !172.16.0.0/12;
    !192.168.0.0/16;
    any;
};
</code></pre><p>Order matters: BIND evaluates rules top to bottom and uses the first match. Put the exclusions before <code>any</code>, or they never apply.</p>
<h2 id="query-restrictions">Query Restrictions <a class="anchor" data-pagefind-ignore href="#query-restrictions" aria-label="Link to this section">#</a></h2>
<p>Three options control who may do what:</p>
<table>
	<thead>
			<tr>
					<th>Option</th>
					<th>Controls</th>
					<th>Typical value</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>allow-recursion</code></td>
					<td>Who may make the server look up names elsewhere</td>
					<td>Your own networks</td>
			</tr>
			<tr>
					<td><code>allow-query</code></td>
					<td>Who may query at all</td>
					<td><code>any</code> on authoritative servers, your networks on resolvers</td>
			</tr>
			<tr>
					<td><code>allow-query-cache</code></td>
					<td>Who may get answers from the cache</td>
					<td>Same as <code>allow-recursion</code></td>
			</tr>
	</tbody>
</table>
<h3 id="restricting-recursion">Restricting Recursion <a class="anchor" data-pagefind-ignore href="#restricting-recursion" aria-label="Link to this section">#</a></h3>
<p>The most critical security setting. Never allow recursion for the entire internet:</p>
<pre tabindex="0"><code>options {
    directory &#34;/var/named&#34;;
    
    // Only allow recursion for trusted networks
    recursion yes;
    allow-recursion { trusted; };
    
    // Alternatively, disable recursion entirely for authoritative-only servers
    // recursion no;
};
</code></pre><h3 id="restricting-queries">Restricting Queries <a class="anchor" data-pagefind-ignore href="#restricting-queries" aria-label="Link to this section">#</a></h3>
<p>Limit who can query your server. An authoritative server must answer anyone; an internal resolver only its own clients. The cache is restricted separately, so outsiders cannot read what your users looked up.</p>
<pre tabindex="0"><code>options {
    // Global query restriction
    allow-query { any; };  // For authoritative servers
    // allow-query { trusted; };  // For internal resolvers
    
    // Restrict cache access
    allow-query-cache { trusted; };
};
</code></pre><h3 id="per-zone-query-restrictions">Per-Zone Query Restrictions <a class="anchor" data-pagefind-ignore href="#per-zone-query-restrictions" aria-label="Link to this section">#</a></h3>
<p>A zone-level <code>allow-query</code> overrides the global one. Here the public zone answers anyone, the internal zone only the internal networks:</p>
<pre tabindex="0"><code>zone &#34;public.example.com&#34; {
    type primary;
    file &#34;zones/public.example.com.zone&#34;;
    allow-query { any; };
};

zone &#34;internal.example.com&#34; {
    type primary;
    file &#34;zones/internal.example.com.zone&#34;;
    allow-query { internal-networks; };
};
</code></pre><h2 id="zone-transfer-security">Zone Transfer Security <a class="anchor" data-pagefind-ignore href="#zone-transfer-security" aria-label="Link to this section">#</a></h2>
<p>A zone transfer (AXFR) hands over every record in the zone at once. Only your slaves need it.</p>
<h3 id="restricting-zone-transfers">Restricting Zone Transfers <a class="anchor" data-pagefind-ignore href="#restricting-zone-transfers" aria-label="Link to this section">#</a></h3>
<p>Deny transfers globally, then allow them per zone for the slaves only. <code>also-notify</code> tells the slaves about changes straight away.</p>
<pre tabindex="0"><code>options {
    // Disable by default
    allow-transfer { none; };
};

zone &#34;example.com&#34; {
    type primary;
    file &#34;zones/example.com.zone&#34;;
    // Only allow transfers to secondary servers
    allow-transfer { secondary-servers; };
    also-notify { 192.168.1.10; 192.168.1.11; };
};
</code></pre><h3 id="tsig-authenticated-transfers">TSIG-Authenticated Transfers <a class="anchor" data-pagefind-ignore href="#tsig-authenticated-transfers" aria-label="Link to this section">#</a></h3>
<p>IP addresses can be spoofed; a TSIG key cannot be guessed. For maximum security, require a signed request. The <a href="https://blog.bsdserver.nl/how-to-configure-bind-rndc-and-tsig-keys-for-remote-dns-management/">rndc and TSIG post</a> shows how to generate the key and configure the slave.</p>
<pre tabindex="0"><code>key &#34;transfer-key&#34; {
    algorithm hmac-sha256;
    secret &#34;base64-encoded-secret&#34;;
};

zone &#34;example.com&#34; {
    type primary;
    file &#34;zones/example.com.zone&#34;;
    allow-transfer { key &#34;transfer-key&#34;; };
};
</code></pre><h2 id="views-for-split-horizon-dns">Views for Split-Horizon DNS <a class="anchor" data-pagefind-ignore href="#views-for-split-horizon-dns" aria-label="Link to this section">#</a></h2>
<p>Views allow the same zone to return different answers based on client IP address. This is essential for split-horizon DNS where internal and external clients need different responses.</p>
<h3 id="when-to-use-views">When to use views <a class="anchor" data-pagefind-ignore href="#when-to-use-views" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use them</strong> when one name must resolve to an internal IP inside and a public IP outside, or when internal-only records must stay invisible from outside.</li>
<li><strong>Skip them</strong> if you can use separate zone names (such as <code>internal.example.com</code>) with a per-zone <code>allow-query</code>; that is simpler.</li>
</ul>
<h3 id="basic-view-configuration">Basic View Configuration <a class="anchor" data-pagefind-ignore href="#basic-view-configuration" aria-label="Link to this section">#</a></h3>
<p>Each view picks its clients with <code>match-clients</code> and has its own copy of the zone, with its own file.</p>
<table>
	<thead>
			<tr>
					<th>View</th>
					<th>Clients</th>
					<th>Recursion</th>
					<th>Zone file</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>internal</code></td>
					<td>Private ranges and localhost</td>
					<td>Yes</td>
					<td><code>zones/internal/example.com.zone</code></td>
			</tr>
			<tr>
					<td><code>external</code></td>
					<td>Everyone else</td>
					<td>No</td>
					<td><code>zones/external/example.com.zone</code></td>
			</tr>
	</tbody>
</table>
<p>Once you use views, every zone must be inside a view. That is why the root hint zone (<code>zone &quot;.&quot;</code>) sits in the internal view: recursion needs it.</p>
<pre tabindex="0"><code>acl &#34;internal&#34; {
    192.168.0.0/16;
    10.0.0.0/8;
    172.16.0.0/12;
    localhost;
};

acl &#34;external&#34; {
    !192.168.0.0/16;
    !10.0.0.0/8;
    !172.16.0.0/12;
    any;
};

view &#34;internal&#34; {
    match-clients { internal; };
    
    // Internal clients get recursion
    recursion yes;
    
    zone &#34;example.com&#34; {
        type primary;
        file &#34;zones/internal/example.com.zone&#34;;
    };
    
    zone &#34;.&#34; {
        type hint;
        file &#34;named.ca&#34;;
    };
};

view &#34;external&#34; {
    match-clients { external; };
    
    // No recursion for external clients
    recursion no;
    
    zone &#34;example.com&#34; {
        type primary;
        file &#34;zones/external/example.com.zone&#34;;
    };
};
</code></pre><h3 id="internal-zone-file">Internal Zone File <a class="anchor" data-pagefind-ignore href="#internal-zone-file" aria-label="Link to this section">#</a></h3>
<p>The internal version includes the private addresses and internal-only hosts like <code>db</code> and <code>ldap</code>.</p>
<pre tabindex="0"><code>; zones/internal/example.com.zone
$TTL 86400
@   IN  SOA ns1.example.com. admin.example.com. (
        2024010101  ; Serial
        3600        ; Refresh
        1800        ; Retry
        604800      ; Expire
        86400 )     ; Minimum TTL

    IN  NS  ns1.example.com.
    IN  NS  ns2.example.com.
    IN  A   192.168.1.100      ; Internal IP

ns1     IN  A   192.168.1.10
ns2     IN  A   192.168.1.11
www     IN  A   192.168.1.100  ; Internal web server
mail    IN  A   192.168.1.50   ; Internal mail server
db      IN  A   192.168.1.200  ; Database - internal only
ldap    IN  A   192.168.1.201  ; LDAP - internal only
</code></pre><h3 id="external-zone-file">External Zone File <a class="anchor" data-pagefind-ignore href="#external-zone-file" aria-label="Link to this section">#</a></h3>
<p>The external version has the public addresses and leaves out internal hosts entirely.</p>
<pre tabindex="0"><code>; zones/external/example.com.zone
$TTL 86400
@   IN  SOA ns1.example.com. admin.example.com. (
        2024010101  ; Serial
        3600        ; Refresh
        1800        ; Retry
        604800      ; Expire
        86400 )     ; Minimum TTL

    IN  NS  ns1.example.com.
    IN  NS  ns2.example.com.
    IN  A   203.0.113.100      ; Public IP
    IN  MX  10 mail.example.com.

ns1     IN  A   203.0.113.10
ns2     IN  A   203.0.113.11
www     IN  A   203.0.113.100  ; Public web server
mail    IN  A   203.0.113.50   ; Public mail server
; No db or ldap records - not accessible externally
</code></pre><h3 id="view-ordering">View Ordering <a class="anchor" data-pagefind-ignore href="#view-ordering" aria-label="Link to this section">#</a></h3>
<p>Views are evaluated in order and a client gets the first view that matches. Place more specific views first and end with a catch-all:</p>
<pre tabindex="0"><code>view &#34;admin&#34; {
    match-clients { 192.168.1.5; };  // Admin workstation
    // Full access, debugging enabled
};

view &#34;internal&#34; {
    match-clients { internal; };
    // Standard internal access
};

view &#34;external&#34; {
    match-clients { any; };  // Catch-all
    // Restricted external access
};
</code></pre><h2 id="rate-limiting">Rate Limiting <a class="anchor" data-pagefind-ignore href="#rate-limiting" aria-label="Link to this section">#</a></h2>
<p>Response Rate Limiting (RRL) protects against DNS amplification and query floods. It counts responses per client network and drops the excess.</p>
<pre tabindex="0"><code>options {
    rate-limit {
        responses-per-second 10;
        referrals-per-second 5;
        nodata-per-second 5;
        nxdomains-per-second 5;
        errors-per-second 5;
        all-per-second 20;
        window 15;
        slip 2;
        ipv4-prefix-length 24;
        ipv6-prefix-length 56;
    };
};
</code></pre><p>Key parameters:</p>
<ul>
<li><code>responses-per-second</code>: limit identical responses.</li>
<li><code>referrals-</code>, <code>nodata-</code>, <code>nxdomains-</code>, <code>errors-per-second</code>: separate limits per response type.</li>
<li><code>all-per-second</code>: limit on all responses to one client network.</li>
<li><code>slip</code>: send truncated responses (forcing TCP) instead of dropping. A real client retries over TCP; a spoofed victim gets nothing large.</li>
<li><code>window</code>: time window for rate calculation.</li>
<li><code>ipv4-prefix-length</code> / <code>ipv6-prefix-length</code>: group clients by /24 (IPv4) or /56 (IPv6) instead of individual IPs.</li>
</ul>
<h2 id="response-policy">Response Policy <a class="anchor" data-pagefind-ignore href="#response-policy" aria-label="Link to this section">#</a></h2>
<h3 id="minimal-responses">Minimal Responses <a class="anchor" data-pagefind-ignore href="#minimal-responses" aria-label="Link to this section">#</a></h3>
<p>Smaller answers make the server less useful as an amplifier:</p>
<ul>
<li><code>minimal-responses yes</code>: leave out optional authority and additional records.</li>
<li><code>minimal-any yes</code>: answer an ANY query with one record set instead of everything for the name.</li>
</ul>
<pre tabindex="0"><code>options {
    minimal-responses yes;
    minimal-any yes;
};
</code></pre><h3 id="disable-any-queries">Disable ANY Queries <a class="anchor" data-pagefind-ignore href="#disable-any-queries" aria-label="Link to this section">#</a></h3>
<p>ANY queries are often used in amplification attacks, because one small query can return every record for a name:</p>
<pre tabindex="0"><code>options {
    minimal-any yes;  // Return minimal response
    // Or block entirely with RPZ
};
</code></pre><h2 id="logging-security-events">Logging Security Events <a class="anchor" data-pagefind-ignore href="#logging-security-events" aria-label="Link to this section">#</a></h2>
<p>Security events and zone transfers go to one file, queries to their own (they grow fast):</p>
<ul>
<li><code>category security</code>: denied queries, transfers and updates.</li>
<li><code>xfer-in</code>, <code>xfer-out</code>, <code>notify</code>: every zone transfer and notify, so you can spot unexpected AXFR attempts.</li>
<li><code>category queries</code>: every query, once query logging is on (<code>rndc querylog</code>).</li>
</ul>
<pre tabindex="0"><code>logging {
    channel security_log {
        file &#34;/var/log/named/security.log&#34; versions 5 size 10m;
        severity info;
        print-time yes;
        print-severity yes;
        print-category yes;
    };
    
    channel query_log {
        file &#34;/var/log/named/queries.log&#34; versions 5 size 50m;
        severity info;
        print-time yes;
    };
    
    category security { security_log; };
    category queries { query_log; };
    category xfer-in { security_log; };
    category xfer-out { security_log; };
    category notify { security_log; };
};
</code></pre><h2 id="complete-secure-configuration-example">Complete Secure Configuration Example <a class="anchor" data-pagefind-ignore href="#complete-secure-configuration-example" aria-label="Link to this section">#</a></h2>
<p>This configuration combines all features above: a split-horizon server that resolves for trusted clients and is authoritative-only for everyone else.</p>
<ul>
<li>Global defaults deny everything risky: recursion, transfers, updates.</li>
<li><code>version</code>, <code>hostname</code>, <code>server-id</code> <code>&quot;not disclosed&quot;</code>: hide the answers to <code>version.bind</code>, <code>hostname.bind</code> and <code>id.server</code>, which attackers use to fingerprint the server.</li>
<li>The views turn recursion back on for trusted clients only. Both copies of <code>example.com</code> allow transfers only with the TSIG key.</li>
</ul>
<pre tabindex="0"><code>// /etc/named.conf

acl &#34;trusted&#34; {
    localhost;
    localnets;
    192.168.0.0/16;
    10.0.0.0/8;
};

acl &#34;secondary-ns&#34; {
    192.168.1.10;
    192.168.1.11;
};

key &#34;transfer-key&#34; {
    algorithm hmac-sha256;
    secret &#34;your-secret-here&#34;;
};

options {
    directory &#34;/var/named&#34;;
    pid-file &#34;/run/named/named.pid&#34;;
    
    // Listen configuration
    listen-on port 53 { any; };
    listen-on-v6 port 53 { any; };
    
    // Security defaults
    recursion no;           // Disabled by default
    allow-query { any; };   // Allow queries
    allow-transfer { none; };  // Deny transfers by default
    allow-update { none; };    // Deny updates by default
    
    // Version hiding
    version &#34;not disclosed&#34;;
    hostname &#34;not disclosed&#34;;
    server-id &#34;not disclosed&#34;;
    
    // Response minimization
    minimal-responses yes;
    minimal-any yes;
    
    // Rate limiting
    rate-limit {
        responses-per-second 10;
        window 15;
        slip 2;
    };
    
    // DNSSEC validation
    dnssec-validation auto;
};

view &#34;internal&#34; {
    match-clients { trusted; };
    
    recursion yes;
    allow-recursion { trusted; };
    
    zone &#34;example.com&#34; {
        type primary;
        file &#34;zones/internal/example.com.zone&#34;;
        allow-transfer { key &#34;transfer-key&#34;; };
    };
    
    zone &#34;.&#34; {
        type hint;
        file &#34;named.ca&#34;;
    };
};

view &#34;external&#34; {
    match-clients { any; };
    
    recursion no;
    
    zone &#34;example.com&#34; {
        type primary;
        file &#34;zones/external/example.com.zone&#34;;
        allow-transfer { key &#34;transfer-key&#34;; };
        allow-query { any; };
    };
};

logging {
    channel default_log {
        file &#34;/var/log/named/named.log&#34; versions 5 size 10m;
        severity info;
        print-time yes;
        print-severity yes;
    };
    
    channel security_log {
        file &#34;/var/log/named/security.log&#34; versions 5 size 10m;
        severity info;
        print-time yes;
    };
    
    category default { default_log; };
    category security { security_log; };
    category xfer-in { security_log; };
    category xfer-out { security_log; };
};
</code></pre><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Likely cause</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Internal clients get external answers</td>
					<td>Client IP not in the internal view&rsquo;s <code>match-clients</code>, or the views are in the wrong order</td>
			</tr>
			<tr>
					<td><code>named-checkconf</code>: zone not in a view</td>
					<td>With views, every zone (also from <code>named.conf.local</code>) must be inside a view</td>
			</tr>
			<tr>
					<td>Internal clients get <code>REFUSED</code> for internet names</td>
					<td>Recursion off or root hint zone missing in their view</td>
			</tr>
			<tr>
					<td>Slave transfer refused</td>
					<td>Slave IP or TSIG key missing from <code>allow-transfer</code>; check the security log</td>
			</tr>
	</tbody>
</table>
<h2 id="security-checklist">Security Checklist <a class="anchor" data-pagefind-ignore href="#security-checklist" aria-label="Link to this section">#</a></h2>
<p>Before putting your BIND server into production:</p>
<ol>
<li><strong>Recursion</strong>: Disabled or restricted to trusted networks only</li>
<li><strong>Zone transfers</strong>: Restricted to secondary servers, preferably with TSIG</li>
<li><strong>Version string</strong>: Hidden to prevent fingerprinting</li>
<li><strong>Rate limiting</strong>: Enabled to prevent amplification abuse</li>
<li><strong>ACLs</strong>: Defined and applied consistently</li>
<li><strong>Views</strong>: Configured if split-horizon is needed</li>
<li><strong>Logging</strong>: Security events logged for auditing</li>
<li><strong>DNSSEC</strong>: Validation enabled for resolvers</li>
<li><strong>Updates</strong>: Disabled or restricted with TSIG keys</li>
<li><strong>Firewall</strong>: Port 53 restricted appropriately</li>
</ol>
<h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub:
<a href="https://github.com/pderuiter/blog-bind-views-acls" rel="noopener">pderuiter/blog-bind-views-acls</a>. It creates an Ubuntu 24.04 VM on Proxmox and applies the complete secure configuration from this post, with the ACLs, the internal and external views, TSIG-only transfers, rate limiting and security logging; put the transfer key in an ansible-vault file, then run <code>terraform apply</code> and <code>ansible-playbook site.yml</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>DNS security requires defense in depth. ACLs provide the foundation, views enable split-horizon deployments, and query restrictions prevent abuse. Rate limiting, minimal responses and logging complete the picture.</p>
<p>The next post will cover dynamic DNS updates with TSIG authentication, allowing secure automated record management.</p>
]]></content:encoded></item><item><title>Setting Up Dynamic DNS Updates with BIND and TSIG Authentication</title><link>https://blog.bsdserver.nl/setting-up-dynamic-dns-updates-with-bind-and-tsig-authentication/</link><guid isPermaLink="false">693b6c4e79eb54000160a567</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:13:50 +0000</pubDate><description>Dynamic DNS (DDNS) allows automated systems to update DNS records in real-time.</description><category>BIND</category><category>DNS</category><category>Dynamic DNS</category><category>TSIG</category><category>DHCP</category><category>Linux</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/bind-dyndns-tsig.png" medium="image"/><content:encoded><![CDATA[<p>Dynamic DNS (DDNS) allows automated systems to update DNS records in real-time. DHCP servers register client hostnames, Kubernetes publishes services, and ACME clients add challenge records, all without anyone editing a zone file.</p>
<p>This post sets up BIND to accept those updates securely with TSIG (Transaction Signature) keys: one key per client, each limited to the names and record types it needs. It ends with Kea DHCP registering every lease in DNS.</p>
<h2 id="why-dynamic-dns-with-tsig">Why Dynamic DNS with TSIG? <a class="anchor" data-pagefind-ignore href="#why-dynamic-dns-with-tsig" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>No zone file editing</strong>: records change through the DNS protocol itself, from scripts or services.</li>
<li><strong>Authenticated</strong>: only clients holding the right key can change anything.</li>
<li><strong>Fine-grained</strong>: <code>update-policy</code> limits each key to specific names and record types.</li>
<li><strong>Standard</strong>: <code>nsupdate</code>, Kea, external-dns and ACME clients all speak it.</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> when records change often or are owned by software: DHCP leases, Kubernetes services, ACME DNS-01 challenges.</li>
<li><strong>Skip it</strong> for zones that only change by hand or through configuration management. A static zone file in Git is easier to review, and a dynamic zone should not be edited by hand (see <a href="#managing-journal-files">Managing Journal Files</a>).</li>
</ul>
<h2 id="how-dynamic-dns-works">How Dynamic DNS Works <a class="anchor" data-pagefind-ignore href="#how-dynamic-dns-works" aria-label="Link to this section">#</a></h2>
<p>Dynamic DNS updates use the DNS UPDATE protocol (RFC 2136). A client sends an update request to the authoritative DNS server, which validates the request and modifies the zone. TSIG keys provide cryptographic authentication to ensure only authorized clients can make changes.</p>
<p>The process:</p>
<ol>
<li>Client generates an update request</li>
<li>Client signs the request with a TSIG key</li>
<li>Server receives and validates the signature</li>
<li>Server applies the update to the zone</li>
<li>Server responds with success or error</li>
</ol>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>TSIG key</td>
					<td>Both sides, same name and secret</td>
					<td>Signs the update; the server checks the signature.</td>
			</tr>
			<tr>
					<td>Zone (<code>type primary</code>) with <code>allow-update</code> / <code>update-policy</code></td>
					<td>BIND</td>
					<td>Decides which key may change which names and types.</td>
			</tr>
			<tr>
					<td>Journal (<code>.jnl</code>)</td>
					<td>BIND, next to the zone file</td>
					<td>Records each update; BIND merges it into the zone file later.</td>
			</tr>
			<tr>
					<td>Update client</td>
					<td><code>nsupdate</code>, Kea D2, external-dns</td>
					<td>Builds and sends the signed update.</td>
			</tr>
	</tbody>
</table>
<p>The flow: client signs update → BIND checks key → checks policy → writes journal → answers with the new record.</p>
<h2 id="generating-tsig-keys">Generating TSIG Keys <a class="anchor" data-pagefind-ignore href="#generating-tsig-keys" aria-label="Link to this section">#</a></h2>
<p>A TSIG key is a shared secret with a name. The server identifies the client by the key name, so the name matters as much as the secret.</p>
<p>Create a dedicated key for dynamic updates and save it where <code>named.conf</code> will include it:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">mkdir -p /etc/named/keys
</span></span><span class="line"><span class="cl">tsig-keygen -a hmac-sha256 ddns-key &gt; /etc/named/keys/ddns.key
</span></span></code></pre></div><p>The paths in this post are the RHEL ones. On Debian/Ubuntu, AppArmor only lets <code>named</code> read <code>/etc/bind</code> and write <code>/var/lib/bind</code> and <code>/var/cache/bind</code>, so it is denied anything under <code>/etc/named</code> or <code>/var/named</code>. Use these paths there instead, everywhere they appear below (or add a local AppArmor override in <code>/etc/apparmor.d/local/usr.sbin.named</code>):</p>
<table>
	<thead>
			<tr>
					<th>RHEL</th>
					<th>Debian/Ubuntu</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>/etc/named/keys/</code></td>
					<td><code>/etc/bind/keys/</code></td>
			</tr>
			<tr>
					<td><code>/var/named/dynamic/</code></td>
					<td><code>/var/lib/bind/dynamic/</code></td>
			</tr>
	</tbody>
</table>
<p>The SELinux steps are RHEL only.</p>
<p>The file contains:</p>
<pre tabindex="0"><code>key &#34;ddns-key&#34; {
    algorithm hmac-sha256;
    secret &#34;X7s8F2pL+Kd9mN1vQ4rT6wY0zA3cE5hG7jU2nM4xB8=&#34;;
};
</code></pre><p>Create one key per client. A leaked key then only exposes what that client may change, and you can revoke it alone:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">tsig-keygen -a hmac-sha256 dhcp-update-key &gt; /etc/named/keys/dhcp.key
</span></span><span class="line"><span class="cl">tsig-keygen -a hmac-sha256 k8s-update-key &gt; /etc/named/keys/kubernetes.key
</span></span><span class="line"><span class="cl">tsig-keygen -a hmac-sha256 admin-update-key &gt; /etc/named/keys/admin.key
</span></span></code></pre></div><p>Secure the key files. <code>named</code> must read them, nobody else:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">chmod <span class="m">640</span> /etc/named/keys/*.key
</span></span><span class="line"><span class="cl">chown root:named /etc/named/keys/*.key    <span class="c1"># Debian/Ubuntu: root:bind</span>
</span></span></code></pre></div><h2 id="configuring-bind-for-dynamic-updates">Configuring BIND for Dynamic Updates <a class="anchor" data-pagefind-ignore href="#configuring-bind-for-dynamic-updates" aria-label="Link to this section">#</a></h2>
<p>Two ways to say who may update a zone:</p>
<table>
	<thead>
			<tr>
					<th>Option</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>allow-update { key &quot;…&quot;; }</code></td>
					<td>One trusted client that may change anything in the zone</td>
			</tr>
			<tr>
					<td><code>update-policy { grant … }</code></td>
					<td>Several clients, each limited to certain names and record types</td>
			</tr>
	</tbody>
</table>
<p>The two cannot be combined in one zone.</p>
<h3 id="basic-update-configuration">Basic Update Configuration <a class="anchor" data-pagefind-ignore href="#basic-update-configuration" aria-label="Link to this section">#</a></h3>
<p>Include the key and configure the zone. <code>allow-update</code> gives <code>ddns-key</code> full control over <code>dynamic.example.com</code>. The journal lists every change so BIND can replay it after a restart.</p>
<pre tabindex="0"><code>// /etc/named.conf

include &#34;/etc/named/keys/ddns.key&#34;;

zone &#34;dynamic.example.com&#34; {
    type primary;
    file &#34;/var/named/dynamic/dynamic.example.com.zone&#34;;
    allow-update { key &#34;ddns-key&#34;; };
    
    // Journal file for tracking updates
    journal &#34;/var/named/dynamic/dynamic.example.com.zone.jnl&#34;;
};
</code></pre><h3 id="multiple-keys-with-different-permissions">Multiple Keys with Different Permissions <a class="anchor" data-pagefind-ignore href="#multiple-keys-with-different-permissions" aria-label="Link to this section">#</a></h3>
<p>Grant different access levels to different keys. Dynamic zones need a directory <code>named</code> can write to for the journal (see <a href="#directory-and-file-permissions">Directory and File Permissions</a>), so they live in <code>/var/named/dynamic</code>:</p>
<ul>
<li>DHCP may only touch A, AAAA and TXT records below <code>internal.example.com</code>.</li>
<li>Kubernetes owns everything below <code>k8s.example.com</code>.</li>
<li>The admin key can change any name in <code>example.com</code>.</li>
</ul>
<pre tabindex="0"><code>include &#34;/etc/named/keys/dhcp.key&#34;;
include &#34;/etc/named/keys/kubernetes.key&#34;;
include &#34;/etc/named/keys/admin.key&#34;;

zone &#34;internal.example.com&#34; {
    type primary;
    file &#34;/var/named/dynamic/internal.example.com.zone&#34;;
    
    // DHCP can only update specific record types
    update-policy {
        grant dhcp-update-key wildcard *.internal.example.com A AAAA;
        grant dhcp-update-key wildcard *.internal.example.com TXT;
    };
};

zone &#34;k8s.example.com&#34; {
    type primary;
    file &#34;/var/named/dynamic/k8s.example.com.zone&#34;;
    
    // Kubernetes can manage its subdomain
    update-policy {
        grant k8s-update-key subdomain k8s.example.com ANY;
    };
};

zone &#34;example.com&#34; {
    type primary;
    file &#34;/var/named/dynamic/example.com.zone&#34;;
    
    // Admin has full control
    update-policy {
        grant admin-update-key zonesub ANY;
    };
};
</code></pre><h3 id="update-policy-rules">Update Policy Rules <a class="anchor" data-pagefind-ignore href="#update-policy-rules" aria-label="Link to this section">#</a></h3>
<p>Each <code>grant</code> line names a key, a rule type that says which names match, and optionally the record types allowed:</p>
<pre tabindex="0"><code>update-policy {
    // Grant based on key name
    grant keyname ruletype name [types];
};
</code></pre><table>
	<thead>
			<tr>
					<th>Rule type</th>
					<th>Matches</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>name</code></td>
					<td>Exact name match (<code>name *.example.com</code> matches only the literal wildcard record, not <code>host1.example.com</code>)</td>
			</tr>
			<tr>
					<td><code>subdomain</code></td>
					<td>Name and all names below it</td>
			</tr>
			<tr>
					<td><code>wildcard</code></td>
					<td>Pattern match with wildcards</td>
			</tr>
			<tr>
					<td><code>zonesub</code></td>
					<td>Any name in the zone</td>
			</tr>
			<tr>
					<td><code>self</code></td>
					<td>Client can update its own name (based on key name)</td>
			</tr>
			<tr>
					<td><code>selfsub</code></td>
					<td>Client can update its name and below</td>
			</tr>
			<tr>
					<td><code>selfwild</code></td>
					<td>Client can update wildcards of its name</td>
			</tr>
	</tbody>
</table>
<p>Examples:</p>
<pre tabindex="0"><code>update-policy {
    // DHCP can add A records for any host in clients subdomain
    grant dhcp-key subdomain clients.example.com A AAAA PTR;
    
    // Let-encrypt can update TXT records for ACME challenges
    grant acme-key name _acme-challenge.example.com TXT;
    
    // Monitoring can update health check records
    grant monitoring-key name health.example.com A TXT;
    
    // Self-registration: any key may update the record that
    // matches its own key name
    grant * self * A AAAA;
};
</code></pre><h2 id="directory-and-file-permissions">Directory and File Permissions <a class="anchor" data-pagefind-ignore href="#directory-and-file-permissions" aria-label="Link to this section">#</a></h2>
<p>BIND writes the journal next to the zone file and rewrites the zone file when it syncs, so it needs write access to that directory. On RHEL, SELinux must also allow it: <code>named_zone_t</code> is the label for writable zone data.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Create directory for dynamic zones</span>
</span></span><span class="line"><span class="cl">mkdir -p /var/named/dynamic
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Set ownership</span>
</span></span><span class="line"><span class="cl">chown named:named /var/named/dynamic
</span></span><span class="line"><span class="cl">chmod <span class="m">750</span> /var/named/dynamic
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># If using SELinux</span>
</span></span><span class="line"><span class="cl">semanage fcontext -a -t named_zone_t <span class="s2">&#34;/var/named/dynamic(/.*)?&#34;</span> 
</span></span><span class="line"><span class="cl">restorecon -Rv /var/named/dynamic
</span></span></code></pre></div><h2 id="sending-dynamic-updates">Sending Dynamic Updates <a class="anchor" data-pagefind-ignore href="#sending-dynamic-updates" aria-label="Link to this section">#</a></h2>
<h3 id="using-nsupdate">Using nsupdate <a class="anchor" data-pagefind-ignore href="#using-nsupdate" aria-label="Link to this section">#</a></h3>
<p><code>nsupdate</code> is the standard client. <code>-k</code> signs the update with the key; <code>send</code> applies everything entered since the last <code>send</code> as one update.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Interactive mode</span>
</span></span><span class="line"><span class="cl">nsupdate -k /etc/named/keys/ddns.key
</span></span><span class="line"><span class="cl">&gt; server ns1.example.com
</span></span><span class="line"><span class="cl">&gt; zone dynamic.example.com
</span></span><span class="line"><span class="cl">&gt; update add newhost.dynamic.example.com <span class="m">300</span> A 192.168.1.100
</span></span><span class="line"><span class="cl">&gt; send
</span></span><span class="line"><span class="cl">&gt; quit
</span></span></code></pre></div><p>From a script:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">nsupdate -k /etc/named/keys/ddns.key <span class="s">&lt;&lt; EOF
</span></span></span><span class="line"><span class="cl"><span class="s">server ns1.example.com
</span></span></span><span class="line"><span class="cl"><span class="s">zone dynamic.example.com
</span></span></span><span class="line"><span class="cl"><span class="s">update delete oldhost.dynamic.example.com A
</span></span></span><span class="line"><span class="cl"><span class="s">update add newhost.dynamic.example.com 300 A 192.168.1.100
</span></span></span><span class="line"><span class="cl"><span class="s">send
</span></span></span><span class="line"><span class="cl"><span class="s">EOF</span>
</span></span></code></pre></div><h3 id="update-operations">Update Operations <a class="anchor" data-pagefind-ignore href="#update-operations" aria-label="Link to this section">#</a></h3>
<p>The commands you combine in an update. There is no &ldquo;replace&rdquo;: delete the old record and add the new one in the same <code>send</code>.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Add a record</span>
</span></span><span class="line"><span class="cl">update add hostname.example.com <span class="m">300</span> A 192.168.1.10
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Delete specific record</span>
</span></span><span class="line"><span class="cl">update delete hostname.example.com A 192.168.1.10
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Delete all records of a type</span>
</span></span><span class="line"><span class="cl">update delete hostname.example.com A
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Delete all records for a name</span>
</span></span><span class="line"><span class="cl">update delete hostname.example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Update (delete + add)</span>
</span></span><span class="line"><span class="cl">update delete hostname.example.com A
</span></span><span class="line"><span class="cl">update add hostname.example.com <span class="m">300</span> A 192.168.1.20
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Add multiple records</span>
</span></span><span class="line"><span class="cl">update add hostname.example.com <span class="m">300</span> A 192.168.1.10
</span></span><span class="line"><span class="cl">update add hostname.example.com <span class="m">300</span> A 192.168.1.11
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Add different record types</span>
</span></span><span class="line"><span class="cl">update add hostname.example.com <span class="m">300</span> A 192.168.1.10
</span></span><span class="line"><span class="cl">update add hostname.example.com <span class="m">300</span> AAAA 2001:db8::10
</span></span><span class="line"><span class="cl">update add hostname.example.com <span class="m">300</span> TXT <span class="s2">&#34;v=spf1 -all&#34;</span>
</span></span></code></pre></div><h3 id="prerequisites-conditional-updates">Prerequisites (Conditional Updates) <a class="anchor" data-pagefind-ignore href="#prerequisites-conditional-updates" aria-label="Link to this section">#</a></h3>
<p>A <code>prereq</code> line makes the update apply only if the condition holds; otherwise the server refuses the whole update. Use it to avoid overwriting a record another client owns.</p>
<table>
	<thead>
			<tr>
					<th>Prerequisite</th>
					<th>Condition</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>nxdomain</code></td>
					<td>The name does not exist</td>
			</tr>
			<tr>
					<td><code>yxdomain</code></td>
					<td>The name exists</td>
			</tr>
			<tr>
					<td><code>yxrrset</code></td>
					<td>The record set exists (with this value, if given)</td>
			</tr>
	</tbody>
</table>
<p>These run against <code>example.com</code>, so they use the admin key that the zone&rsquo;s <code>update-policy</code> grants. Comments inside nsupdate input start with <code>;</code>. A <code>#</code> line makes nsupdate abort with <code>incorrect section name: #</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">nsupdate -k /etc/named/keys/admin.key <span class="s">&lt;&lt; EOF
</span></span></span><span class="line"><span class="cl"><span class="s">server ns1.example.com
</span></span></span><span class="line"><span class="cl"><span class="s">zone example.com
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">; Only add if record doesn&#39;t exist
</span></span></span><span class="line"><span class="cl"><span class="s">prereq nxdomain newhost.example.com
</span></span></span><span class="line"><span class="cl"><span class="s">update add newhost.example.com 300 A 192.168.1.10
</span></span></span><span class="line"><span class="cl"><span class="s">send
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">; Only update if record exists
</span></span></span><span class="line"><span class="cl"><span class="s">prereq yxdomain oldhost.example.com
</span></span></span><span class="line"><span class="cl"><span class="s">update delete oldhost.example.com A
</span></span></span><span class="line"><span class="cl"><span class="s">update add oldhost.example.com 300 A 192.168.1.20
</span></span></span><span class="line"><span class="cl"><span class="s">send
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">; Only update if specific record exists
</span></span></span><span class="line"><span class="cl"><span class="s">prereq yxrrset oldhost.example.com A 192.168.1.20
</span></span></span><span class="line"><span class="cl"><span class="s">update delete oldhost.example.com A
</span></span></span><span class="line"><span class="cl"><span class="s">update add oldhost.example.com 300 A 192.168.1.30
</span></span></span><span class="line"><span class="cl"><span class="s">send
</span></span></span><span class="line"><span class="cl"><span class="s">EOF</span>
</span></span></code></pre></div><h2 id="integrating-with-kea-dhcp">Integrating with Kea DHCP <a class="anchor" data-pagefind-ignore href="#integrating-with-kea-dhcp" aria-label="Link to this section">#</a></h2>
<p>ISC DHCP (<code>dhcpd</code>) reached end of life in 2022; its successor is ISC Kea. Kea splits the work over two daemons:</p>
<ul>
<li><code>kea-dhcp4</code> hands out leases and queues DNS changes.</li>
<li><code>kea-dhcp-ddns</code> (D2) sends the signed updates to BIND, adding A, DHCID and PTR records when a lease is assigned and removing them again when the lease is released.</li>
</ul>
<p>On Debian/Ubuntu:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo apt install -y kea-dhcp4-server kea-dhcp-ddns-server
</span></span></code></pre></div><h3 id="dhcp-server-configuration">DHCP Server Configuration <a class="anchor" data-pagefind-ignore href="#dhcp-server-configuration" aria-label="Link to this section">#</a></h3>
<p><code>kea-dhcp4</code> decides what name a client gets and hands the DNS work to D2. The DDNS settings:</p>
<ul>
<li><code>dhcp-ddns.enable-updates</code>: send DNS changes to D2 on localhost.</li>
<li><code>ddns-send-updates</code> with <code>ddns-override-client-update</code>: Kea updates forward and reverse zones itself, even if the client offers to do its own.</li>
<li><code>ddns-qualifying-suffix</code>: appended to the client&rsquo;s hostname, giving <code>host.internal.example.com.</code>.</li>
<li><code>ddns-replace-client-name: when-not-present</code> with <code>ddns-generated-prefix</code>: clients without a hostname get a generated name like <code>dhcp-192-168-1-100</code>.</li>
<li><code>hostname-char-set</code> / <code>hostname-char-replacement</code>: characters not allowed in DNS names become <code>-</code>.</li>
</ul>
<pre tabindex="0"><code>// /etc/kea/kea-dhcp4.conf
{
  &#34;Dhcp4&#34;: {
    &#34;interfaces-config&#34;: {
      &#34;interfaces&#34;: [ &#34;eth0&#34; ]
    },

    &#34;lease-database&#34;: {
      &#34;type&#34;: &#34;memfile&#34;,
      &#34;persist&#34;: true,
      &#34;name&#34;: &#34;/var/lib/kea/kea-leases4.csv&#34;
    },

    // Hand DNS work to kea-dhcp-ddns (D2) on localhost
    &#34;dhcp-ddns&#34;: {
      &#34;enable-updates&#34;: true
    },

    // Kea updates both forward and reverse zones itself,
    // even if the client asks to do its own forward update
    &#34;ddns-send-updates&#34;: true,
    &#34;ddns-override-client-update&#34;: true,
    &#34;ddns-qualifying-suffix&#34;: &#34;internal.example.com.&#34;,

    // Clients without a hostname get dhcp-192-168-1-100 etc.
    &#34;ddns-replace-client-name&#34;: &#34;when-not-present&#34;,
    &#34;ddns-generated-prefix&#34;: &#34;dhcp&#34;,
    &#34;hostname-char-set&#34;: &#34;[^A-Za-z0-9.-]&#34;,
    &#34;hostname-char-replacement&#34;: &#34;-&#34;,

    &#34;subnet4&#34;: [
      {
        &#34;id&#34;: 1,
        &#34;subnet&#34;: &#34;192.168.1.0/24&#34;,
        &#34;pools&#34;: [ { &#34;pool&#34;: &#34;192.168.1.100 - 192.168.1.200&#34; } ],
        &#34;option-data&#34;: [
          { &#34;name&#34;: &#34;routers&#34;, &#34;data&#34;: &#34;192.168.1.1&#34; },
          { &#34;name&#34;: &#34;domain-name&#34;, &#34;data&#34;: &#34;internal.example.com&#34; },
          { &#34;name&#34;: &#34;domain-name-servers&#34;, &#34;data&#34;: &#34;192.168.1.10&#34; }
        ]
      }
    ]
  }
}
</code></pre><h3 id="dhcp-ddns-d2-configuration">DHCP-DDNS (D2) Configuration <a class="anchor" data-pagefind-ignore href="#dhcp-ddns-d2-configuration" aria-label="Link to this section">#</a></h3>
<p>D2 holds the TSIG key and knows which server is authoritative for each zone. Paste the secret from <code>tsig-keygen -a hmac-sha256 dhcp-key</code>:</p>
<ul>
<li><code>tsig-keys</code>: same name and secret as the key in BIND.</li>
<li><code>forward-ddns</code> / <code>reverse-ddns</code>: per zone, the key to sign with and the DNS server to send updates to.</li>
</ul>
<pre tabindex="0"><code>// /etc/kea/kea-dhcp-ddns.conf
{
  &#34;DhcpDdns&#34;: {
    &#34;ip-address&#34;: &#34;127.0.0.1&#34;,
    &#34;port&#34;: 53001,

    // Key for DNS updates (same name and secret as in BIND)
    &#34;tsig-keys&#34;: [
      {
        &#34;name&#34;: &#34;dhcp-key&#34;,
        &#34;algorithm&#34;: &#34;HMAC-SHA256&#34;,
        &#34;secret&#34;: &#34;your-secret-from-tsig-keygen&#34;
      }
    ],

    // Forward zone
    &#34;forward-ddns&#34;: {
      &#34;ddns-domains&#34;: [
        {
          &#34;name&#34;: &#34;internal.example.com.&#34;,
          &#34;key-name&#34;: &#34;dhcp-key&#34;,
          &#34;dns-servers&#34;: [ { &#34;ip-address&#34;: &#34;192.168.1.10&#34; } ]
        }
      ]
    },

    // Reverse zone
    &#34;reverse-ddns&#34;: {
      &#34;ddns-domains&#34;: [
        {
          &#34;name&#34;: &#34;1.168.192.in-addr.arpa.&#34;,
          &#34;key-name&#34;: &#34;dhcp-key&#34;,
          &#34;dns-servers&#34;: [ { &#34;ip-address&#34;: &#34;192.168.1.10&#34; } ]
        }
      ]
    }
  }
}
</code></pre><p>The file contains the secret and the daemons run as <code>_kea</code>, so protect it, check both files and restart the services:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo chown root:_kea /etc/kea/kea-dhcp-ddns.conf
</span></span><span class="line"><span class="cl">sudo chmod <span class="m">640</span> /etc/kea/kea-dhcp-ddns.conf
</span></span><span class="line"><span class="cl">sudo kea-dhcp4 -t /etc/kea/kea-dhcp4.conf
</span></span><span class="line"><span class="cl">sudo kea-dhcp-ddns -t /etc/kea/kea-dhcp-ddns.conf
</span></span><span class="line"><span class="cl">sudo systemctl restart kea-dhcp-ddns-server kea-dhcp4-server
</span></span></code></pre></div><h3 id="bind-configuration-for-dhcp">BIND Configuration for DHCP <a class="anchor" data-pagefind-ignore href="#bind-configuration-for-dhcp" aria-label="Link to this section">#</a></h3>
<p>The matching zones on the BIND side. <code>dhcp-key</code> may only manage address, PTR and DHCID records. DHCID records let Kea tell its own records apart from ones it did not create.</p>
<pre tabindex="0"><code>// Forward zone
zone &#34;internal.example.com&#34; {
    type primary;
    file &#34;/var/named/dynamic/internal.example.com.zone&#34;;
    update-policy {
        grant dhcp-key subdomain internal.example.com A AAAA DHCID;
    };
};

// Reverse zone
zone &#34;1.168.192.in-addr.arpa&#34; {
    type primary;
    file &#34;/var/named/dynamic/192.168.1.rev&#34;;
    update-policy {
        grant dhcp-key subdomain 1.168.192.in-addr.arpa PTR DHCID;
    };
};
</code></pre><p>Kea also writes a DHCID record next to the PTR in the reverse zone, so the reverse policy must allow <code>DHCID</code> as well; without it D2 logs <code>DHCP_DDNS_REVERSE_REPLACE_REJECTED ... RCODE: 5</code> and the PTR is never created.</p>
<h2 id="reverse-dns-updates">Reverse DNS Updates <a class="anchor" data-pagefind-ignore href="#reverse-dns-updates" aria-label="Link to this section">#</a></h2>
<p>Without Kea you send the PTR records yourself. Reverse zones are separate zones, so each needs its own update.</p>
<p>Use a key that the target zone&rsquo;s <code>allow-update</code>/<code>update-policy</code> grants. With the DHCP configuration above, that is <code>dhcp-key</code> for both zones; any other key gets <code>REFUSED</code> (or <code>NOTAUTH(BADKEY)</code> if the server doesn&rsquo;t know it):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">nsupdate -k /etc/named/keys/ddns.key <span class="s">&lt;&lt; EOF
</span></span></span><span class="line"><span class="cl"><span class="s">server ns1.example.com
</span></span></span><span class="line"><span class="cl"><span class="s">zone 1.168.192.in-addr.arpa
</span></span></span><span class="line"><span class="cl"><span class="s">update add 100.1.168.192.in-addr.arpa 300 PTR hostname.example.com.
</span></span></span><span class="line"><span class="cl"><span class="s">send
</span></span></span><span class="line"><span class="cl"><span class="s">EOF</span>
</span></span></code></pre></div><p>Script for simultaneous forward and reverse updates. It derives the reverse name and zone from the IP (assuming a /24 reverse zone), then replaces the A and PTR records:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># Stop on the first failed nsupdate instead of reporting success</span>
</span></span><span class="line"><span class="cl"><span class="nb">set</span> -e
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">HOSTNAME</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$1</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">IP</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$2</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">ZONE</span><span class="o">=</span><span class="s2">&#34;internal.example.com&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">KEY</span><span class="o">=</span><span class="s2">&#34;/etc/named/keys/ddns.key&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">SERVER</span><span class="o">=</span><span class="s2">&#34;ns1.example.com&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">TTL</span><span class="o">=</span><span class="m">300</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate reverse zone from IP</span>
</span></span><span class="line"><span class="cl"><span class="nv">IFS</span><span class="o">=</span><span class="s1">&#39;.&#39;</span> <span class="nb">read</span> -ra OCTETS <span class="o">&lt;&lt;&lt;</span> <span class="s2">&#34;</span><span class="nv">$IP</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">REVERSE</span><span class="o">=</span><span class="s2">&#34;</span><span class="si">${</span><span class="nv">OCTETS</span><span class="p">[3]</span><span class="si">}</span><span class="s2">.</span><span class="si">${</span><span class="nv">OCTETS</span><span class="p">[2]</span><span class="si">}</span><span class="s2">.</span><span class="si">${</span><span class="nv">OCTETS</span><span class="p">[1]</span><span class="si">}</span><span class="s2">.</span><span class="si">${</span><span class="nv">OCTETS</span><span class="p">[0]</span><span class="si">}</span><span class="s2">.in-addr.arpa&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">REVZONE</span><span class="o">=</span><span class="s2">&#34;</span><span class="si">${</span><span class="nv">OCTETS</span><span class="p">[2]</span><span class="si">}</span><span class="s2">.</span><span class="si">${</span><span class="nv">OCTETS</span><span class="p">[1]</span><span class="si">}</span><span class="s2">.</span><span class="si">${</span><span class="nv">OCTETS</span><span class="p">[0]</span><span class="si">}</span><span class="s2">.in-addr.arpa&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Update forward zone</span>
</span></span><span class="line"><span class="cl">nsupdate -k <span class="s2">&#34;</span><span class="nv">$KEY</span><span class="s2">&#34;</span> <span class="s">&lt;&lt; EOF
</span></span></span><span class="line"><span class="cl"><span class="s">server $SERVER
</span></span></span><span class="line"><span class="cl"><span class="s">zone $ZONE
</span></span></span><span class="line"><span class="cl"><span class="s">update delete ${HOSTNAME}.${ZONE} A
</span></span></span><span class="line"><span class="cl"><span class="s">update add ${HOSTNAME}.${ZONE} $TTL A $IP
</span></span></span><span class="line"><span class="cl"><span class="s">send
</span></span></span><span class="line"><span class="cl"><span class="s">EOF</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Update reverse zone</span>
</span></span><span class="line"><span class="cl">nsupdate -k <span class="s2">&#34;</span><span class="nv">$KEY</span><span class="s2">&#34;</span> <span class="s">&lt;&lt; EOF
</span></span></span><span class="line"><span class="cl"><span class="s">server $SERVER
</span></span></span><span class="line"><span class="cl"><span class="s">zone $REVZONE
</span></span></span><span class="line"><span class="cl"><span class="s">update delete $REVERSE PTR
</span></span></span><span class="line"><span class="cl"><span class="s">update add $REVERSE $TTL PTR ${HOSTNAME}.${ZONE}.
</span></span></span><span class="line"><span class="cl"><span class="s">send
</span></span></span><span class="line"><span class="cl"><span class="s">EOF</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;Updated: </span><span class="si">${</span><span class="nv">HOSTNAME</span><span class="si">}</span><span class="s2">.</span><span class="si">${</span><span class="nv">ZONE</span><span class="si">}</span><span class="s2"> -&gt; </span><span class="nv">$IP</span><span class="s2">&#34;</span>
</span></span></code></pre></div><h2 id="managing-journal-files">Managing Journal Files <a class="anchor" data-pagefind-ignore href="#managing-journal-files" aria-label="Link to this section">#</a></h2>
<p>BIND stores dynamic updates in journal files before merging them with the zone file. The zone file on disk can therefore be behind what BIND serves. Never edit it while updates are enabled.</p>
<table>
	<thead>
			<tr>
					<th>Command</th>
					<th>What it does</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>rndc freeze</code></td>
					<td>Writes the journal into the zone file and stops updates</td>
					<td>Manual edits</td>
			</tr>
			<tr>
					<td><code>rndc thaw</code></td>
					<td>Reloads the zone file and enables updates again</td>
					<td>After manual edits</td>
			</tr>
			<tr>
					<td><code>rndc sync</code></td>
					<td>Writes the journal into the zone file, updates keep working</td>
					<td>Backups, reading the file</td>
			</tr>
			<tr>
					<td><code>rndc sync -clean</code></td>
					<td>Same, and removes the journal</td>
					<td>Cleaning up a large journal</td>
			</tr>
	</tbody>
</table>
<h3 id="freeze-and-thaw">Freeze and Thaw <a class="anchor" data-pagefind-ignore href="#freeze-and-thaw" aria-label="Link to this section">#</a></h3>
<p>To manually edit a dynamic zone:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Freeze zone (syncs journal to zone file)</span>
</span></span><span class="line"><span class="cl">rndc freeze example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Edit the zone file manually</span>
</span></span><span class="line"><span class="cl">vim /var/named/dynamic/example.com.zone
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Update serial number!</span>
</span></span><span class="line"><span class="cl"><span class="c1"># Thaw zone (re-enables dynamic updates)</span>
</span></span><span class="line"><span class="cl">rndc thaw example.com
</span></span></code></pre></div><h3 id="sync-without-freezing">Sync Without Freezing <a class="anchor" data-pagefind-ignore href="#sync-without-freezing" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Sync journal to zone file without freezing</span>
</span></span><span class="line"><span class="cl">rndc sync example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Sync and clear journal</span>
</span></span><span class="line"><span class="cl">rndc sync -clean example.com
</span></span></code></pre></div><h3 id="viewing-zone-contents">Viewing Zone Contents <a class="anchor" data-pagefind-ignore href="#viewing-zone-contents" aria-label="Link to this section">#</a></h3>
<p>To see what BIND actually serves, dump it from memory or transfer the zone. AXFR only works from a host the zone&rsquo;s <code>allow-transfer</code> permits.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Dump zone including dynamic updates</span>
</span></span><span class="line"><span class="cl">rndc dumpdb -zones
</span></span><span class="line"><span class="cl"><span class="c1"># RHEL: /var/named/data/cache_dump.db, Debian/Ubuntu: /var/cache/bind/named_dump.db</span>
</span></span><span class="line"><span class="cl">cat /var/named/data/cache_dump.db <span class="p">|</span> grep -A100 <span class="s2">&#34;example.com&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Or view via dig</span>
</span></span><span class="line"><span class="cl">dig @localhost example.com AXFR
</span></span></code></pre></div><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<h3 id="enable-update-logging">Enable Update Logging <a class="anchor" data-pagefind-ignore href="#enable-update-logging" aria-label="Link to this section">#</a></h3>
<p>The <code>update</code> category logs every update; <code>update-security</code> logs the ones that were refused. Send both to a file while debugging:</p>
<pre tabindex="0"><code>logging {
    channel update_log {
        file &#34;/var/log/named/update.log&#34; versions 5 size 10m;
        severity debug;
        print-time yes;
        print-category yes;
    };
    
    category update { update_log; };
    category update-security { update_log; };
};
</code></pre><h3 id="common-errors">Common Errors <a class="anchor" data-pagefind-ignore href="#common-errors" aria-label="Link to this section">#</a></h3>
<table>
	<thead>
			<tr>
					<th>Error</th>
					<th>Causes</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>NOTAUTH(BADKEY)</code></td>
					<td>Key not configured on the server, or key name mismatch</td>
			</tr>
			<tr>
					<td><code>NOTAUTH(BADSIG)</code></td>
					<td>Same key name, but the secret doesn&rsquo;t match</td>
			</tr>
			<tr>
					<td><code>REFUSED</code></td>
					<td>Update policy doesn&rsquo;t allow the operation for this key, name or type; or update sent without a key to a zone that requires one</td>
			</tr>
			<tr>
					<td><code>NOTAUTH</code></td>
					<td>Server is not authoritative for the zone; or zone name incorrect</td>
			</tr>
			<tr>
					<td><code>SERVFAIL</code></td>
					<td>Zone file or journal file permission issues; filesystem full</td>
			</tr>
	</tbody>
</table>
<p>What each looks like in nsupdate:</p>
<p><strong>NOTAUTH(BADKEY) / NOTAUTH(BADSIG)</strong></p>
<pre tabindex="0"><code>; TSIG error with server: tsig indicates error
update failed: NOTAUTH(BADKEY)
</code></pre><p><strong>REFUSED</strong></p>
<pre tabindex="0"><code>update failed: REFUSED
</code></pre><p><strong>NOTAUTH</strong></p>
<pre tabindex="0"><code>update failed: NOTAUTH
</code></pre><p><strong>SERVFAIL</strong></p>
<pre tabindex="0"><code>update failed: SERVFAIL
</code></pre><h3 id="debug-mode">Debug Mode <a class="anchor" data-pagefind-ignore href="#debug-mode" aria-label="Link to this section">#</a></h3>
<p><code>-d</code> prints debug output for each step, including the reply from the server:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Verbose nsupdate</span>
</span></span><span class="line"><span class="cl">nsupdate -d -k /etc/named/keys/admin.key <span class="s">&lt;&lt; EOF
</span></span></span><span class="line"><span class="cl"><span class="s">server ns1.example.com
</span></span></span><span class="line"><span class="cl"><span class="s">zone example.com
</span></span></span><span class="line"><span class="cl"><span class="s">update add test.example.com 300 A 192.168.1.99
</span></span></span><span class="line"><span class="cl"><span class="s">send
</span></span></span><span class="line"><span class="cl"><span class="s">EOF</span>
</span></span></code></pre></div><h3 id="check-permissions">Check Permissions <a class="anchor" data-pagefind-ignore href="#check-permissions" aria-label="Link to this section">#</a></h3>
<p>For <code>SERVFAIL</code>, check file ownership and, on RHEL, SELinux labels and denials:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Zone file and directory permissions</span>
</span></span><span class="line"><span class="cl">ls -la /var/named/dynamic/
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># SELinux context</span>
</span></span><span class="line"><span class="cl">ls -laZ /var/named/dynamic/
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check for SELinux denials</span>
</span></span><span class="line"><span class="cl">ausearch -m AVC -ts recent <span class="p">|</span> grep named
</span></span></code></pre></div><h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<h3 id="limit-update-scope">Limit Update Scope <a class="anchor" data-pagefind-ignore href="#limit-update-scope" aria-label="Link to this section">#</a></h3>
<p>Never use <code>allow-update { any; }</code>. Always restrict updates:</p>
<pre tabindex="0"><code>// Bad - anyone can update
allow-update { any; };

// Good - only authenticated clients
allow-update { key &#34;update-key&#34;; };

// Better - granular policy
update-policy {
    grant update-key subdomain clients.example.com A AAAA;
};
</code></pre><h3 id="separate-keys-per-service">Separate Keys per Service <a class="anchor" data-pagefind-ignore href="#separate-keys-per-service" aria-label="Link to this section">#</a></h3>
<p>Each service should have its own key with minimum required permissions:</p>
<pre tabindex="0"><code>update-policy {
    // DHCP only manages client records
    grant dhcp-key subdomain clients.internal.example.com A AAAA PTR DHCID;
    
    // Let&#39;s Encrypt only manages ACME challenges
    grant acme-key name _acme-challenge.example.com TXT;
    
    // Kubernetes only manages its namespace
    grant k8s-key subdomain k8s.example.com A AAAA SRV;
};
</code></pre><h3 id="protect-key-files">Protect Key Files <a class="anchor" data-pagefind-ignore href="#protect-key-files" aria-label="Link to this section">#</a></h3>
<p>Anyone with the key file can change your zone. Keep the server&rsquo;s copies readable only by <code>named</code>, and give each client only its own key:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># 440, not 400: named runs as the named user and reads keys via the group</span>
</span></span><span class="line"><span class="cl">chmod <span class="m">440</span> /etc/named/keys/*.key
</span></span><span class="line"><span class="cl">chown root:named /etc/named/keys/*.key
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># For client systems, only the specific key they need</span>
</span></span><span class="line"><span class="cl"><span class="c1"># (Kea keeps it inside the D2 config, read by the _kea user)</span>
</span></span><span class="line"><span class="cl">chmod <span class="m">640</span> /etc/kea/kea-dhcp-ddns.conf
</span></span><span class="line"><span class="cl">chown root:_kea /etc/kea/kea-dhcp-ddns.conf
</span></span></code></pre></div><h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub:
<a href="https://github.com/pderuiter/blog-bind-dynamic-dns" rel="noopener">pderuiter/blog-bind-dynamic-dns</a>. It creates a BIND server with the dynamic zones, keys and update policies from this post, plus a Kea DHCP server whose D2 daemon registers every lease in DNS; put your TSIG secrets in an ansible-vault file, then run <code>terraform apply</code> and <code>ansible-playbook site.yml</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>TSIG keys plus <code>update-policy</code> let DHCP, Kubernetes and automation update DNS safely, each within its own part of the zone.</p>
<p>The next post will cover integrating BIND with Kubernetes external-dns for automated service discovery and DNS management.</p>
]]></content:encoded></item><item><title>Set Up Bind DNS for Catalog Zones</title><link>https://blog.bsdserver.nl/how-to-set-up-bind-dns-for-catalog-zones/</link><guid isPermaLink="false">693b500279eb54000160a446</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Thu, 11 Dec 2025 23:13:06 +0000</pubDate><description>Ever wondered how to manage thousands of slave zones in Bind?</description><category>DNS</category><category>BIND</category><category>Linux</category><category>Sysadmin</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/bind-catalog-zones.png" medium="image"/><content:encoded><![CDATA[<p>Ever wondered how to manage thousands of slave zones in Bind? A few slave zones are easy to maintain by hand. When you regularly add domains, every new zone means editing the configuration on every slave server.</p>
<p>ISC Bind&rsquo;s &ldquo;Catalog Zones&rdquo; solve that. The master publishes a special zone that lists all member zones; slaves read it and add or remove those zones on their own. This post sets up one master and one slave with a catalog zone.</p>
<h2 id="why-catalog-zones">Why Catalog Zones? <a class="anchor" data-pagefind-ignore href="#why-catalog-zones" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>One place to add a zone</strong>: add it on the master and to the catalog; the slaves follow.</li>
<li><strong>No slave configuration changes</strong>: slaves create and delete member zones automatically.</li>
<li><strong>Standard DNS transport</strong>: the catalog is an ordinary zone, transferred with AXFR/IXFR like any other.</li>
<li><strong>Per-zone settings</strong>: metadata in the catalog can set masters or transfer ACLs for one member zone.</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> when you host many zones, or add and remove zones often, across several slaves.</li>
<li><strong>Skip it</strong> for a handful of zones that rarely change; plain <code>zone</code> blocks are simpler.</li>
</ul>
<h2 id="how-it-works">How It Works <a class="anchor" data-pagefind-ignore href="#how-it-works" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Catalog zone <code>catalog.example.com</code></td>
					<td>Master (<code>10.71.0.176</code>), transferred to the slave</td>
					<td>Lists the member zones as <code>PTR</code> records</td>
			</tr>
			<tr>
					<td>Member zones (e.g. <code>example.org</code>)</td>
					<td>Master, added with <code>rndc addzone</code></td>
					<td>The real zones with your records</td>
			</tr>
			<tr>
					<td><code>catalog-zones</code> option</td>
					<td>Slave (<code>10.71.0.177</code>)</td>
					<td>Reads the catalog and creates or deletes member zones</td>
			</tr>
	</tbody>
</table>
<p>The flow: add a member zone on the master → add its PTR record to the catalog and bump the serial → the slave transfers the catalog → it creates the member zone → it transfers the member zone from the master.</p>
<h2 id="step-1-configure-the-master-server">Step 1: Configure the Master Server <a class="anchor" data-pagefind-ignore href="#step-1-configure-the-master-server" aria-label="Link to this section">#</a></h2>
<p>The master needs <code>allow-new-zones yes</code>, which lets <code>rndc addzone</code> create zones at runtime without editing <code>named.conf</code> (used in Step 3).</p>
<pre tabindex="0"><code>options {
    directory &#34;/etc/namedb&#34;;
    ...
    server-id &#34;authoritative&#34;;
    allow-new-zones yes;
};
</code></pre><p><code>/etc/namedb</code> is the BIND directory on FreeBSD. On Debian/Ubuntu, AppArmor only lets <code>named</code> write to <code>/var/lib/bind</code> and <code>/var/cache/bind</code>, so use the packaged <code>directory &quot;/var/cache/bind&quot;;</code> there (RHEL: <code>/var/named</code>). The relative file names below (<code>catalog.example.com.db</code>, <code>example.org</code>, <code>cat-zones</code>) then land in that directory, e.g. <code>/var/cache/bind/cat-zones</code>. Alternatively, add a local AppArmor override in <code>/etc/apparmor.d/local/usr.sbin.named</code>.</p>
<p>Next, create the catalog zone file. It starts empty: only the SOA, a dummy NS record (required in every zone, never used) and the format version.</p>
<pre tabindex="0"><code>$TTL 3600
@       IN SOA . . 1 86400 3600 86400 3600
@       IN NS  ns1.
version IN TXT &#34;2&#34;
</code></pre><p>Save it as <code>/etc/namedb/catalog.example.com.db</code> and serve it as an ordinary master zone that the slave may transfer. The catalog&rsquo;s NS record is a dummy, so notify the slave explicitly:</p>
<pre tabindex="0"><code>zone &#34;catalog.example.com&#34; {
    type master;
    file &#34;catalog.example.com.db&#34;;
    allow-transfer { 10.71.0.177; };
    also-notify { 10.71.0.177; };
};
</code></pre><h2 id="step-2-configure-the-slave-server">Step 2: Configure the Slave Server <a class="anchor" data-pagefind-ignore href="#step-2-configure-the-slave-server" aria-label="Link to this section">#</a></h2>
<p>The slave also needs <code>allow-new-zones yes</code>, plus a <code>catalog-zones</code> block that names the catalog to follow:</p>
<ul>
<li><code>zone &quot;catalog.example.com&quot;</code>: the catalog this slave reads.</li>
<li><code>zone-directory &quot;cat-zones&quot;</code>: where the member zone files are stored.</li>
<li><code>in-memory no</code>: write member zones to disk, so they survive a restart without a new transfer.</li>
<li><code>default-masters</code>: where to transfer member zones from, unless the catalog says otherwise.</li>
<li><code>masterfile-format text</code>: store zone files as readable text instead of the binary format.</li>
</ul>
<pre tabindex="0"><code>options {
    directory &#34;/etc/namedb&#34;;
    ...
    masterfile-format text;
    zone-statistics yes;
    server-id &#34;slave&#34;;

    allow-new-zones yes;
    catalog-zones {
        zone &#34;catalog.example.com&#34;
              zone-directory &#34;cat-zones&#34;
              in-memory no
              default-masters { 10.71.0.176; };
    };
};
</code></pre><p>Bind does not create the <code>cat-zones</code> directory. If it is missing, it logs <code>zone-directory 'cat-zones' not found; zone files will not be saved</code>, so create it first:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">mkdir /etc/namedb/cat-zones
</span></span><span class="line"><span class="cl">chown bind:bind /etc/namedb/cat-zones    <span class="c1"># the user named runs as (bind on FreeBSD/Debian, named on RHEL)</span>
</span></span></code></pre></div><p>The catalog itself is an ordinary slave zone, transferred from the master:</p>
<pre tabindex="0"><code>zone &#34;catalog.example.com&#34; {
    type slave;
    file &#34;catalog.example.com.db&#34;;
    masters { 10.71.0.176; };
};
</code></pre><h2 id="step-3-add-a-new-member-zone">Step 3: Add a New Member Zone <a class="anchor" data-pagefind-ignore href="#step-3-add-a-new-member-zone" aria-label="Link to this section">#</a></h2>
<p>Adding a zone is two steps: create it on the master, then list it in the catalog (Step 4). Create its zone file (<code>/etc/namedb/example.org</code>) and use <code>rndc</code> to add the new zone to the master server. The zone configuration must end with <code>};</code> <em>inside</em> the quotes; otherwise named rejects it with <code>addzone: missing ';' before end of file</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">rndc addzone example.org <span class="s1">&#39;{type master; file &#34;example.org&#34;;};&#39;</span>
</span></span><span class="line"><span class="cl">dig +short @127.0.0.1 example.org soa
</span></span></code></pre></div><p>The <code>dig</code> checks that the master now serves the zone.</p>
<p>Each member zone gets a unique label in the catalog. The convention is the SHA-1 hash of the zone name in DNS wire format. This Python script calculates it:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="ch">#!/usr/bin/env python3</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">dns.name</span>   <span class="c1"># pip install dnspython</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">hashlib</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">sys</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">print</span><span class="p">(</span><span class="n">hashlib</span><span class="o">.</span><span class="n">sha1</span><span class="p">(</span><span class="n">dns</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">from_text</span><span class="p">(</span><span class="n">sys</span><span class="o">.</span><span class="n">argv</span><span class="p">[</span><span class="mi">1</span><span class="p">])</span><span class="o">.</span><span class="n">to_wire</span><span class="p">())</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">())</span>
</span></span></code></pre></div><p>To generate the hash for <code>example.org</code>, run:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">./nzf.py example.org
</span></span><span class="line"><span class="cl">47ac1a4d93b61fffdb4762c18c9e7d1a6b046d33
</span></span></code></pre></div><p>Alternatively, you could use <code>openssl</code> to generate the hash:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nb">printf</span> <span class="s1">&#39;\7example\3org\0&#39;</span> <span class="p">|</span> openssl sha1
</span></span><span class="line"><span class="cl">SHA1<span class="o">(</span>stdin<span class="o">)=</span> 47ac1a4d93b61fffdb4762c18c9e7d1a6b046d33
</span></span></code></pre></div><p>With catalog format version 2 the label only has to be unique within the catalog, so the hash is a convenient convention rather than a requirement.</p>
<h2 id="step-4-update-the-catalog-zone">Step 4: Update the Catalog Zone <a class="anchor" data-pagefind-ignore href="#step-4-update-the-catalog-zone" aria-label="Link to this section">#</a></h2>
<p>The PTR record <code>&lt;hash&gt;.zones PTR example.org.</code> is what tells the slaves that <code>example.org</code> is a member zone. Increase the SOA serial so the slave picks up the change. Keep the <code>version</code> record. Without it the slave logs <code>catz: zone 'catalog.example.com' has no 'version' record</code> and ignores the whole catalog:</p>
<pre tabindex="0"><code>@ 3600 SOA . . 2 86400 3600 86400 3600
@ 3600 IN NS nop.
version 3600 IN TXT &#34;2&#34;

47ac1a4d93b61fffdb4762c18c9e7d1a6b046d33.zones PTR example.org.
</code></pre><p>Reload on the master to load the new catalog and notify the slave:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">rndc reload
</span></span></code></pre></div><p>The master&rsquo;s log shows the slave transferring first the catalog, then the new member zone:</p>
<pre tabindex="0"><code>xfer-out: info: client 10.71.0.177#33213 (catalog.example.com): transfer of &#39;catalog.example.com/IN&#39;: AXFR-style IXFR started (serial 2)
xfer-out: info: client 10.71.0.177#33213 (catalog.example.com): transfer of &#39;catalog.example.com/IN&#39;: AXFR-style IXFR ended
xfer-out: info: client 10.71.0.177#45095 (example.org): transfer of &#39;example.org/IN&#39;: AXFR started (serial 22)
xfer-out: info: client 10.71.0.177#45095 (example.org): transfer of &#39;example.org/IN&#39;: AXFR ended
</code></pre><h2 id="verifying-the-setup-on-the-secondary">Verifying the Setup on the Secondary <a class="anchor" data-pagefind-ignore href="#verifying-the-setup-on-the-secondary" aria-label="Link to this section">#</a></h2>
<p>The new zone should now exist on the secondary server. Check the <code>cat-zones</code> directory for the slaved zone:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">ls -l /etc/namedb/cat-zones
</span></span><span class="line"><span class="cl">-rw-r--r-- <span class="m">1</span> <span class="nb">bind</span> <span class="nb">bind</span>  <span class="m">340</span> Jun  <span class="m">2</span> 13:33 __catz___default_catalog.example.com_example.org.db
</span></span></code></pre></div><p>The <code>_default</code> part of the name is the view the catalog belongs to.</p>
<p>The <code>__catz__*</code> file contains a copy of the slaved zone.</p>
<p>To remove a member zone, delete its PTR record from the catalog and bump the serial. The slave then deletes the zone itself, as its log shows:</p>
<pre tabindex="0"><code>catz: updating catalog zone &#39;catalog.example.com&#39; with serial 3
catz: deleting zone &#39;example.org&#39; from catalog &#39;catalog.example.com&#39; - success
catz: catz_delzone_taskaction: zone &#39;example.org&#39; deleted
</code></pre><h2 id="using-metadata-in-catalog-zones">Using Metadata in Catalog Zones <a class="anchor" data-pagefind-ignore href="#using-metadata-in-catalog-zones" aria-label="Link to this section">#</a></h2>
<p>Metadata overrides the slave&rsquo;s defaults for one member zone. In a version &ldquo;2&rdquo; catalog these custom properties live under an <code>ext</code> label. Bind logs <code>invalid record in catalog zone ... - ignoring</code> for the version 1 style <code>masters.&lt;hash&gt;.zones</code>.</p>
<table>
	<thead>
			<tr>
					<th>Property</th>
					<th>Record type</th>
					<th>Overrides</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>masters.ext.&lt;hash&gt;.zones</code></td>
					<td><code>A</code></td>
					<td><code>default-masters</code>: where this zone is transferred from</td>
			</tr>
			<tr>
					<td><code>allow-transfer.ext.&lt;hash&gt;.zones</code></td>
					<td><code>APL</code></td>
					<td>Who may transfer this zone from the slave</td>
			</tr>
	</tbody>
</table>
<p>For instance, you can assign a different master server to a particular member zone:</p>
<pre tabindex="0"><code>47ac1a4d93b61fffdb4762c18c9e7d1a6b046d33.zones                 IN PTR example.org.
masters.ext.47ac1a4d93b61fffdb4762c18c9e7d1a6b046d33.zones   IN A 10.71.0.144
</code></pre><p>You can also set Address Prefix Lists (APLs) to control zone transfers on a per-zone basis:</p>
<pre tabindex="0"><code>allow-transfer.ext.47ac1a4d93b61fffdb4762c18c9e7d1a6b046d33.zones   IN APL  1:10.71.0.177/32 1:10.71.0.247/32
</code></pre><p>This example allows zone transfers from two specific IP addresses.</p>
<h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Log message / symptom</th>
					<th>Cause / fix</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>zone-directory 'cat-zones' not found</code></td>
					<td>Create the directory, owned by the BIND user</td>
			</tr>
			<tr>
					<td><code>has no 'version' record</code></td>
					<td>Add <code>version IN TXT &quot;2&quot;</code> to the catalog</td>
			</tr>
			<tr>
					<td><code>invalid record in catalog zone ... - ignoring</code></td>
					<td>Version 1 syntax in a version 2 catalog; use the <code>ext</code> label</td>
			</tr>
			<tr>
					<td><code>addzone: missing ';' before end of file</code></td>
					<td>End the zone configuration with <code>};</code> inside the quotes</td>
			</tr>
			<tr>
					<td>Slave ignores a catalog change</td>
					<td>SOA serial not increased</td>
			</tr>
	</tbody>
</table>
<h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Whoever controls the catalog controls the slaves</strong>: restrict <code>allow-transfer</code> on the catalog zone to your slaves.</li>
<li><strong>Sign transfers with TSIG</strong>: catalog zones support TSIG for the catalog and the member zones (see the <a href="https://blog.bsdserver.nl/how-to-configure-bind-rndc-and-tsig-keys-for-remote-dns-management/">rndc and TSIG post</a>).</li>
</ul>
<h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub:
<a href="https://github.com/pderuiter/blog-bind-catalog-zones" rel="noopener">pderuiter/blog-bind-catalog-zones</a>. It creates the master and the slave, sets up the catalog zone and adds each member zone with <code>rndc addzone</code> and its hashed catalog record; list your zones in <code>group_vars/all/vars.yml</code>, then run <code>terraform apply</code> and <code>ansible-playbook site.yml</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>Catalog zones turn adding a slave zone into two commands on the master: <code>rndc addzone</code> and one catalog record. The slaves follow on their own, however many zones you host.</p>
]]></content:encoded></item><item><title>Enabling DNSSEC Validation on BIND Resolvers</title><link>https://blog.bsdserver.nl/enabling-dnssec-validation-on-bind-resolvers/</link><guid isPermaLink="false">693b6dbb79eb54000160a58e</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:19:55 +0000</pubDate><description>DNSSEC (Domain Name System Security Extensions) adds cryptographic authentication to DNS responses, protecting against cache poisoning and…</description><category>BIND</category><category>DNS</category><category>DNSSEC</category><category>Security</category><category>Linux</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/bind-dnssec-validation.png" medium="image"/><content:encoded><![CDATA[<p>DNSSEC (Domain Name System Security Extensions) adds cryptographic authentication to DNS responses, protecting against cache poisoning and man-in-the-middle attacks. A plain resolver accepts whatever answer arrives first; it cannot tell a forged response from a real one.</p>
<p>This post turns a BIND recursive resolver into a validating resolver. It covers enabling validation, testing it, handling domains with broken DNSSEC, and monitoring the result.</p>
<h2 id="why-dnssec-validation">Why DNSSEC validation? <a class="anchor" data-pagefind-ignore href="#why-dnssec-validation" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Tamper detection</strong>: a forged or modified answer fails signature checks and never reaches the client.</li>
<li><strong>Protects every client</strong>: laptops, servers and IoT devices behind the resolver get validation without any client changes.</li>
<li><strong>Low effort</strong>: modern BIND ships the root trust anchor; one setting turns it on.</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> on every recursive resolver you run. Most signed zones validate fine, and the default in current BIND is already <code>auto</code>.</li>
<li><strong>Skip it</strong> only on a forwarder that sends everything to an upstream resolver you trust to validate, or where the clock cannot be kept accurate (signatures have validity periods).</li>
</ul>
<h2 id="how-dnssec-validation-works">How DNSSEC Validation Works <a class="anchor" data-pagefind-ignore href="#how-dnssec-validation-works" aria-label="Link to this section">#</a></h2>
<p>DNSSEC creates a chain of trust from the DNS root zone down to individual domains:</p>
<table>
	<thead>
			<tr>
					<th>Level</th>
					<th>Signed by</th>
					<th>Role in validation</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Root zone</td>
					<td>ICANN</td>
					<td>Its key is the trust anchor, built into DNS software</td>
			</tr>
			<tr>
					<td>TLD (.com, .org)</td>
					<td>The registry</td>
					<td>Root holds a DS record for the TLD key</td>
			</tr>
			<tr>
					<td>Domain</td>
					<td>The domain owner</td>
					<td>TLD holds a DS record for the domain key</td>
			</tr>
			<tr>
					<td>Resolver</td>
					<td>-</td>
					<td>Checks every signature up to the trust anchor</td>
			</tr>
	</tbody>
</table>
<p>When the resolver receives a signed response, it fetches the zone&rsquo;s DNSKEY records, verifies the RRSIG on the answer, checks the DS record in the parent zone, and repeats up to the root trust anchor.</p>
<p>The flow: client query → resolver fetches answer + RRSIG → DNSKEY → DS in parent → … → root trust anchor → answer with <code>ad</code> flag, or SERVFAIL if any signature fails.</p>
<h2 id="enabling-dnssec-validation-in-bind">Enabling DNSSEC Validation in BIND <a class="anchor" data-pagefind-ignore href="#enabling-dnssec-validation-in-bind" aria-label="Link to this section">#</a></h2>
<p>There are two ways to tell BIND which root key to trust:</p>
<table>
	<thead>
			<tr>
					<th>Option</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>dnssec-validation auto</code></td>
					<td>Almost every resolver. BIND uses its built-in root anchor and keeps it current itself.</td>
			</tr>
			<tr>
					<td><code>dnssec-validation yes</code> + <code>trust-anchors</code></td>
					<td>Explicit control, or setups where you manage anchors yourself. You must update them on a root key rollover.</td>
			</tr>
	</tbody>
</table>
<h3 id="automatic-configuration">Automatic Configuration <a class="anchor" data-pagefind-ignore href="#automatic-configuration" aria-label="Link to this section">#</a></h3>
<p>This is the recommended setup. Add <code>dnssec-validation auto</code> to the <code>options</code> block of a recursive resolver:</p>
<pre tabindex="0"><code>options {
    directory &#34;/var/named&#34;;
    
    recursion yes;
    allow-recursion { trusted; };
    
    dnssec-validation auto;
};
</code></pre><ul>
<li><code>dnssec-validation auto</code>: use the built-in managed trust anchors for the root zone. BIND keeps them up to date through RFC 5011 automated trust anchor maintenance.</li>
<li><code>allow-recursion { trusted; }</code>: only your own networks may use the resolver (the <code>trusted</code> ACL is defined in the complete configuration below).</li>
</ul>
<h3 id="manual-trust-anchor-configuration">Manual Trust Anchor Configuration <a class="anchor" data-pagefind-ignore href="#manual-trust-anchor-configuration" aria-label="Link to this section">#</a></h3>
<p>Use this only if you need explicit control. Include both root KSKs: the root zone rolled from KSK-2017 (key tag 20326) to KSK-2024 (key tag 38696) in October 2026, and the root DNSKEY set is now signed by 38696. A fresh resolver that only knows 20326 returns SERVFAIL for every signed name.</p>
<pre tabindex="0"><code>trust-anchors {
    // KSK-2017 (20326), still published in the root zone during the rollover
    . initial-key 257 3 8 &#34;AwEAAaz/tAm8yTn4Mfeh5eyI96WSVexTBAvkMgJzkKTOiW1vkIbzxeF3
        +/4RgWOq7HrxRixHlFlExOLAJr5emLvN7SWXgnLh4+B5xQlNVz8Og8kv
        ArMtNROxVQuCaSnIDdD5LKyWbRd2n9WGe2R8PzgCmr3EgVLrjyBxWezF
        0jLHwVN8efS3rCj/EWgvIWgb9tarpVUDK/b58Da+sqqls3eNbuv7pr+e
        oZG+SrDK6nWeL3c6H5Apxz7LjVc1uTIdsIXxuOLYA4/ilBmSVIzuDWfd
        RUfhHdY6+cn8HFRm+2hM8AnXGXws9555KrUB5qihylGa8subX2Nn6UwN
        R1AkUTV74bU=&#34;;
    // KSK-2024 (38696), the key that signs the root DNSKEY set
    . initial-ds 38696 8 2 &#34;683D2D0ACB8C9B712A1948B27F741219298D0A450D612C483AF444A4C0FB2B16&#34;;
};

options {
    dnssec-validation yes;
};
</code></pre><ul>
<li><code>initial-key</code>: the full public key. <code>initial-ds</code>: only its hash (DS format).</li>
<li><code>initial-*</code> anchors are a starting point; BIND then maintains them with RFC 5011, like <code>auto</code> does.</li>
<li><code>dnssec-validation yes</code>: validate using the configured anchors instead of the built-in ones.</li>
</ul>
<p>These are the same anchors BIND ships in <code>bind.keys</code>; copy them from there when the root rolls again.</p>
<h3 id="verify-dnssec-is-working">Verify DNSSEC Is Working <a class="anchor" data-pagefind-ignore href="#verify-dnssec-is-working" aria-label="Link to this section">#</a></h3>
<p>Query a signed domain with <code>+dnssec</code> and look at the flags line:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Query a signed domain</span>
</span></span><span class="line"><span class="cl">dig @localhost dnssec-tools.org +dnssec
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Look for &#39;ad&#39; (Authenticated Data) flag</span>
</span></span><span class="line"><span class="cl">dig @localhost example.com +dnssec <span class="p">|</span> grep flags
</span></span><span class="line"><span class="cl"><span class="p">;;</span> flags: qr rd ra ad<span class="p">;</span> QUERY: 1, ANSWER: 2, AUTHORITY: 0, ADDITIONAL: <span class="m">1</span>
</span></span></code></pre></div><p>The <code>ad</code> (Authenticated Data) flag means the resolver validated the response.</p>
<h3 id="test-with-known-goodbad-domains">Test with Known Good/Bad Domains <a class="anchor" data-pagefind-ignore href="#test-with-known-goodbad-domains" aria-label="Link to this section">#</a></h3>
<p>A deliberately broken domain is the quickest proof that validation is really on. If <code>dnssec-failed.org</code> resolves, validation is off.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Should succeed (valid DNSSEC)</span>
</span></span><span class="line"><span class="cl">dig @localhost www.dnssec-tools.org
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Should fail with SERVFAIL (deliberately broken DNSSEC)</span>
</span></span><span class="line"><span class="cl">dig @localhost www.dnssec-failed.org
</span></span></code></pre></div><h2 id="handling-dnssec-failures">Handling DNSSEC Failures <a class="anchor" data-pagefind-ignore href="#handling-dnssec-failures" aria-label="Link to this section">#</a></h2>
<h3 id="why-queries-fail">Why Queries Fail <a class="anchor" data-pagefind-ignore href="#why-queries-fail" aria-label="Link to this section">#</a></h3>
<p>A validating resolver returns SERVFAIL when it cannot verify an answer. Common causes:</p>
<table>
	<thead>
			<tr>
					<th>Cause</th>
					<th>Typical origin</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Expired signatures</td>
					<td>RRSIG past its validity; the zone stopped re-signing</td>
			</tr>
			<tr>
					<td>DS mismatch</td>
					<td>Zone keys changed but the parent DS record was not updated</td>
			</tr>
			<tr>
					<td>Broken key rollover</td>
					<td>Keys replaced without a proper rollover</td>
			</tr>
			<tr>
					<td>Truncated response</td>
					<td>UDP size issues with large DNSSEC answers</td>
			</tr>
			<tr>
					<td>Missing DNSKEY</td>
					<td>Network issues prevent fetching the DNSKEY records</td>
			</tr>
	</tbody>
</table>
<h3 id="diagnosing-failures">Diagnosing Failures <a class="anchor" data-pagefind-ignore href="#diagnosing-failures" aria-label="Link to this section">#</a></h3>
<p><code>delv</code> (DNSSEC lookup and validation utility) validates like BIND does and shows where the chain breaks:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check validation chain</span>
</span></span><span class="line"><span class="cl">delv @localhost example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Verbose output</span>
</span></span><span class="line"><span class="cl">delv @localhost example.com +vtrace
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Show trust chain</span>
</span></span><span class="line"><span class="cl">delv @localhost example.com +rtrace
</span></span></code></pre></div><ul>
<li><code>+vtrace</code>: show each validation step.</li>
<li><code>+rtrace</code>: show the queries made to build the trust chain.</li>
</ul>
<p>Example failure output:</p>
<pre tabindex="0"><code>;; resolution failed: broken trust chain
</code></pre><p><code>delv</code> only reports the result class. The specific reason (for example <code>verify failed due to bad signature (keyid=30617): RRSIG has expired</code>) is logged by <code>named</code> in the <code>dnssec</code> category.</p>
<h3 id="check-signature-validity">Check Signature Validity <a class="anchor" data-pagefind-ignore href="#check-signature-validity" aria-label="Link to this section">#</a></h3>
<p>Look at the records that make up the chain: the signatures, the zone keys and the DS in the parent.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># View RRSIG records and expiration</span>
</span></span><span class="line"><span class="cl">dig @localhost example.com RRSIG +short
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check DNSKEY records</span>
</span></span><span class="line"><span class="cl">dig @localhost example.com DNSKEY +short
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check DS record at parent</span>
</span></span><span class="line"><span class="cl">dig @localhost example.com DS +short
</span></span></code></pre></div><h2 id="negative-trust-anchors-ntas">Negative Trust Anchors (NTAs) <a class="anchor" data-pagefind-ignore href="#negative-trust-anchors-ntas" aria-label="Link to this section">#</a></h2>
<p>Sometimes a domain you need has broken DNSSEC that its owner has not fixed. A Negative Trust Anchor turns validation off for that one domain, temporarily, while the rest stays protected.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Add NTA (valid for 1 hour by default)</span>
</span></span><span class="line"><span class="cl">rndc nta example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Add NTA with specific lifetime</span>
</span></span><span class="line"><span class="cl">rndc nta -lifetime <span class="m">3600</span> example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># List active NTAs</span>
</span></span><span class="line"><span class="cl">rndc nta -dump
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Remove NTA</span>
</span></span><span class="line"><span class="cl">rndc nta -remove example.com
</span></span></code></pre></div><h3 id="persistent-ntas">Persistent NTAs <a class="anchor" data-pagefind-ignore href="#persistent-ntas" aria-label="Link to this section">#</a></h3>
<p><code>rndc nta</code> entries expire. For a permanent exception, use <code>validate-except</code> in named.conf:</p>
<pre tabindex="0"><code>options {
    dnssec-validation auto;
    
    // Permanent negative trust anchors
    // Use sparingly - security trade-off!
    validate-except { &#34;broken-domain.example.com&#34;; };
};
</code></pre><p>There is no <code>nta</code> statement in named.conf; <code>validate-except</code> is the permanent equivalent of <code>rndc nta</code>.</p>
<p><strong>Warning</strong>: NTAs disable DNSSEC protection for that domain. Use only when necessary and investigate the root cause.</p>
<h2 id="edns-buffer-size">EDNS Buffer Size <a class="anchor" data-pagefind-ignore href="#edns-buffer-size" aria-label="Link to this section">#</a></h2>
<p>DNSSEC responses are larger than regular DNS answers. Large UDP packets get fragmented, and fragments are often dropped, which shows up as timeouts and SERVFAIL. Cap the UDP size so large answers fall back to TCP instead:</p>
<pre tabindex="0"><code>options {
    edns-udp-size 1232;
    max-udp-size 1232;
};
</code></pre><ul>
<li><code>edns-udp-size</code>: the buffer size BIND advertises in its own queries upstream.</li>
<li><code>max-udp-size</code>: the largest UDP response BIND sends to clients.</li>
</ul>
<p>The 1232 value avoids fragmentation on most networks (1280 IPv6 minimum MTU - 48 header bytes).</p>
<h2 id="logging-dnssec-events">Logging DNSSEC Events <a class="anchor" data-pagefind-ignore href="#logging-dnssec-events" aria-label="Link to this section">#</a></h2>
<p>Send the <code>dnssec</code> category to its own file. That is where the exact reason for a validation failure ends up.</p>
<pre tabindex="0"><code>logging {
    channel dnssec_log {
        file &#34;/var/log/named/dnssec.log&#34; versions 5 size 10m;
        severity info;
        print-time yes;
        print-category yes;
        print-severity yes;
    };
    
    category dnssec { dnssec_log; };
};
</code></pre><p>Log messages show:</p>
<ul>
<li>Successful validations</li>
<li>Validation failures with reason</li>
<li>Trust anchor updates (RFC 5011)</li>
<li>Key rollover events</li>
</ul>
<h2 id="trust-anchor-management">Trust Anchor Management <a class="anchor" data-pagefind-ignore href="#trust-anchor-management" aria-label="Link to this section">#</a></h2>
<h3 id="automatic-updates-rfc-5011">Automatic Updates (RFC 5011) <a class="anchor" data-pagefind-ignore href="#automatic-updates-rfc-5011" aria-label="Link to this section">#</a></h3>
<p>With <code>dnssec-validation auto</code>, BIND manages root trust anchors automatically and stores them in <code>managed-keys.bind</code>. Check their state with <code>rndc</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># View managed keys</span>
</span></span><span class="line"><span class="cl">rndc managed-keys status
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Force refresh</span>
</span></span><span class="line"><span class="cl">rndc managed-keys refresh
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check managed keys database</span>
</span></span><span class="line"><span class="cl">cat /var/named/managed-keys.bind
</span></span></code></pre></div><h3 id="key-rollover-events">Key Rollover Events <a class="anchor" data-pagefind-ignore href="#key-rollover-events" aria-label="Link to this section">#</a></h3>
<p>When the root zone key changes (rare), BIND follows RFC 5011:</p>
<ol>
<li>Detects the new key in the root DNSKEY response</li>
<li>Waits a hold-down period (30 days default)</li>
<li>Adds the new key to the trust store</li>
<li>Removes the old key after it is no longer advertised</li>
</ol>
<p>Monitor for key rollover (with the logging configuration above, these messages go to the <code>dnssec</code> channel):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">grep <span class="s2">&#34;managed-keys&#34;</span> /var/log/named/dnssec.log
</span></span></code></pre></div><h2 id="complete-resolver-configuration">Complete Resolver Configuration <a class="anchor" data-pagefind-ignore href="#complete-resolver-configuration" aria-label="Link to this section">#</a></h2>
<p>This combines everything above into one <code>named.conf</code>:</p>
<pre tabindex="0"><code>// /etc/named.conf

acl &#34;trusted&#34; {
    localhost;
    localnets;
    192.168.0.0/16;
    10.0.0.0/8;
};

options {
    directory &#34;/var/named&#34;;
    pid-file &#34;/run/named/named.pid&#34;;
    
    // Network settings
    listen-on port 53 { any; };
    listen-on-v6 port 53 { any; };
    
    // Recursion settings
    recursion yes;
    allow-recursion { trusted; };
    allow-query-cache { trusted; };
    
    // DNSSEC validation
    dnssec-validation auto;
    
    // EDNS settings for DNSSEC
    edns-udp-size 1232;
    max-udp-size 1232;
    
    // Security
    version &#34;not disclosed&#34;;
    minimal-responses yes;
    
    // Performance
    prefetch 10 60;
};

logging {
    channel default_log {
        file &#34;/var/log/named/named.log&#34; versions 5 size 10m;
        severity info;
        print-time yes;
        print-severity yes;
    };
    
    channel dnssec_log {
        file &#34;/var/log/named/dnssec.log&#34; versions 5 size 10m;
        severity debug;
        print-time yes;
        print-category yes;
    };
    
    category default { default_log; };
    category dnssec { dnssec_log; };
};

zone &#34;.&#34; {
    type hint;
    file &#34;named.ca&#34;;
};
</code></pre><p>What the settings outside DNSSEC do:</p>
<ul>
<li><code>acl &quot;trusted&quot;</code>: the networks allowed to use the resolver; used by <code>allow-recursion</code> and <code>allow-query-cache</code>.</li>
<li><code>version &quot;not disclosed&quot;</code>: hide the BIND version from <code>version.bind</code> queries.</li>
<li><code>minimal-responses yes</code>: leave optional records out of answers; smaller responses.</li>
<li><code>prefetch 10 60</code>: refresh popular records shortly before they expire, so clients do not wait for a cache miss.</li>
<li><code>severity debug</code> on <code>dnssec_log</code>: more detail than the earlier example; lower it to <code>info</code> once things work.</li>
</ul>
<h2 id="testing-dnssec-validation">Testing DNSSEC Validation <a class="anchor" data-pagefind-ignore href="#testing-dnssec-validation" aria-label="Link to this section">#</a></h2>
<h3 id="command-line-tests">Command Line Tests <a class="anchor" data-pagefind-ignore href="#command-line-tests" aria-label="Link to this section">#</a></h3>
<p>Run these after every config change. Signed domains should show <code>ad</code>, broken ones SERVFAIL, unsigned ones resolve without <code>ad</code>.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check if validation is enabled</span>
</span></span><span class="line"><span class="cl">dig @localhost . SOA +dnssec <span class="p">|</span> grep -E <span class="s2">&#34;(flags|ad)&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test known-good signed domain</span>
</span></span><span class="line"><span class="cl">dig @localhost cloudflare.com +dnssec +short
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test validation failure (should return SERVFAIL)</span>
</span></span><span class="line"><span class="cl">dig @localhost dnssec-failed.org
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check AD flag on signed domain</span>
</span></span><span class="line"><span class="cl">dig @localhost sigok.verteiltesysteme.net <span class="p">|</span> grep <span class="s2">&#34;flags:&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check that AD flag is absent for unsigned domain (no &#34;ad&#34; in the flags line)</span>
</span></span><span class="line"><span class="cl">dig @localhost unsigned-domain.com <span class="p">|</span> grep <span class="s2">&#34;flags:&#34;</span>
</span></span></code></pre></div><h3 id="using-drill-from-ldns">Using drill (from ldns) <a class="anchor" data-pagefind-ignore href="#using-drill-from-ldns" aria-label="Link to this section">#</a></h3>
<p><code>drill</code> traces the chain from the root and shows each signature it checks, a useful second opinion next to <code>delv</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Trace DNSSEC chain</span>
</span></span><span class="line"><span class="cl">drill -DT cloudflare.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Show signature details</span>
</span></span><span class="line"><span class="cl">drill -TD cloudflare.com
</span></span></code></pre></div><h2 id="monitoring-dnssec-health">Monitoring DNSSEC Health <a class="anchor" data-pagefind-ignore href="#monitoring-dnssec-health" aria-label="Link to this section">#</a></h2>
<h3 id="statistics">Statistics <a class="anchor" data-pagefind-ignore href="#statistics" aria-label="Link to this section">#</a></h3>
<p>BIND counts validation results. <code>rndc stats</code> writes them to the statistics file:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># View DNSSEC statistics (written to statistics-file, default &#34;named.stats&#34; in the working directory)</span>
</span></span><span class="line"><span class="cl">rndc stats
</span></span><span class="line"><span class="cl">grep <span class="s2">&#34;DNSSEC&#34;</span> /var/named/named.stats
</span></span></code></pre></div><p>The text dump labels these counters &ldquo;DNSSEC validation attempted/succeeded/failed&rdquo;. In the XML/JSON statistics channel they are called:</p>
<ul>
<li><code>ValOk</code>: Successful validations</li>
<li><code>ValNegOk</code>: Validated negative responses</li>
<li><code>ValFail</code>: Validation failures</li>
<li><code>ValIndeterminate</code>: Non-DNSSEC responses</li>
</ul>
<h3 id="alerting-on-failures">Alerting on Failures <a class="anchor" data-pagefind-ignore href="#alerting-on-failures" aria-label="Link to this section">#</a></h3>
<p>This check queries a signed domain and fails if the <code>ad</code> flag is missing. It fits Nagios-style monitoring (exit 2 = critical).</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># /usr/local/bin/check-dnssec.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">RESULT</span><span class="o">=</span><span class="k">$(</span>dig @localhost cloudflare.com +dnssec +short 2&gt;<span class="p">&amp;</span>1<span class="k">)</span>
</span></span><span class="line"><span class="cl"><span class="nv">AD_FLAG</span><span class="o">=</span><span class="k">$(</span>dig @localhost cloudflare.com <span class="p">|</span> grep -cE <span class="s2">&#34;flags:.* ad[ ;]&#34;</span><span class="k">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">if</span> <span class="o">[</span> <span class="nv">$AD_FLAG</span> -eq <span class="m">0</span> <span class="o">]</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">    <span class="nb">echo</span> <span class="s2">&#34;CRITICAL: DNSSEC validation not working&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="nb">exit</span> <span class="m">2</span>
</span></span><span class="line"><span class="cl"><span class="k">fi</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;OK: DNSSEC validation operational&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nb">exit</span> <span class="m">0</span>
</span></span></code></pre></div><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Likely cause</th>
					<th>Check</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>SERVFAIL for one signed domain</td>
					<td>Broken DNSSEC on that domain, or authoritative servers unreachable</td>
					<td><code>+cd</code> query, <code>delv</code>, <code>dnssec.log</code></td>
			</tr>
			<tr>
					<td>SERVFAIL for every signed domain</td>
					<td>Clock wrong, or stale trust anchor</td>
					<td><code>date</code>, <code>rndc managed-keys status</code></td>
			</tr>
			<tr>
					<td>No <code>ad</code> flag anywhere</td>
					<td>Validation off</td>
					<td><code>dnssec-validation</code> setting</td>
			</tr>
	</tbody>
</table>
<h3 id="servfail-for-dnssec-domains">&ldquo;SERVFAIL&rdquo; for DNSSEC Domains <a class="anchor" data-pagefind-ignore href="#servfail-for-dnssec-domains" aria-label="Link to this section">#</a></h3>
<p>First check that the resolver can reach the authoritative servers, then repeat the query with validation disabled:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Try direct query to authoritative</span>
</span></span><span class="line"><span class="cl">dig @ns1.example.com example.com DNSKEY
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check if DNSKEY is retrievable</span>
</span></span><span class="line"><span class="cl">dig @localhost example.com DNSKEY +cd
</span></span></code></pre></div><p>The <code>+cd</code> flag (Checking Disabled) bypasses validation - if this works but normal query fails, the issue is DNSSEC.</p>
<h3 id="clock-skew">Clock Skew <a class="anchor" data-pagefind-ignore href="#clock-skew" aria-label="Link to this section">#</a></h3>
<p>DNSSEC signatures have validity periods. A wrong system clock makes valid signatures look expired or not yet valid:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check time</span>
</span></span><span class="line"><span class="cl">date
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Sync time (chrony)</span>
</span></span><span class="line"><span class="cl">chronyc makestep
</span></span><span class="line"><span class="cl"><span class="c1"># or</span>
</span></span><span class="line"><span class="cl">timedatectl set-ntp <span class="nb">true</span>
</span></span></code></pre></div><h3 id="trust-anchor-problems">Trust Anchor Problems <a class="anchor" data-pagefind-ignore href="#trust-anchor-problems" aria-label="Link to this section">#</a></h3>
<p>If the managed keys are missing or stale, every signed domain fails. Check the managed keys state and file:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check managed keys</span>
</span></span><span class="line"><span class="cl">rndc managed-keys status
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Verify root key file exists</span>
</span></span><span class="line"><span class="cl">ls -la /var/named/managed-keys.bind
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check key validity (the file stores KEYDATA records with key id and &#34;trusted since&#34;)</span>
</span></span><span class="line"><span class="cl">grep -A12 <span class="s2">&#34;KEYDATA&#34;</span> /var/named/managed-keys.bind
</span></span></code></pre></div><h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub: <a href="https://github.com/pderuiter/blog-bind-dnssec-validation" rel="noopener">pderuiter/blog-bind-dnssec-validation</a>. Terraform creates an Ubuntu 24.04 VM on Proxmox, and <code>ansible-playbook site.yml</code> turns it into the validating resolver from this post, including the logging channels and the <code>check-dnssec.sh</code> script; <code>tests/verify.yml</code> runs the checks above.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>DNSSEC validation on your resolver protects all clients from DNS spoofing attacks. Turn it on with <code>dnssec-validation auto</code>, log the <code>dnssec</code> category, watch the validation counters, and use Negative Trust Anchors only for domains whose DNSSEC is broken.</p>
<p>The next post will cover signing your own zones with DNSSEC on authoritative servers, completing the DNSSEC trust chain for your domains.</p>
]]></content:encoded></item><item><title>Signing Your DNS Zones with DNSSEC on BIND Authoritative Servers</title><link>https://blog.bsdserver.nl/signing-your-dns-zones-with-dnssec-on-bind-authoritative-servers/</link><guid isPermaLink="false">693b6e4179eb54000160a599</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:22:09 +0000</pubDate><description>After configuring DNSSEC validation on your resolvers, the next step is signing your own authoritative zones.</description><category>BIND</category><category>DNS</category><category>DNSSEC</category><category>Security</category><category>Homelab</category><category>Linux</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/bind-dnssec.png" medium="image"/><content:encoded><![CDATA[<p>After configuring DNSSEC validation on your resolvers, the next step is signing your own authoritative zones. Without signatures, a validating resolver has nothing to check: your records can still be forged in transit.</p>
<p>This post signs zones on a BIND authoritative server. It covers key types and algorithms, a manual signing run to show the moving parts, automated signing with <code>dnssec-policy</code>, publishing the DS record, and key rollovers.</p>
<h2 id="why-sign-your-zones">Why sign your zones? <a class="anchor" data-pagefind-ignore href="#why-sign-your-zones" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Authentic answers</strong>: validating resolvers can prove your records came from you, unmodified.</li>
<li><strong>Completes the chain of trust</strong>: the DS record in the parent zone links your zone to the root.</li>
<li><strong>Enables DNSSEC-based features</strong>: records like TLSA (DANE) and SSHFP are only trusted when signed.</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> for public zones you control, where your registrar supports DS records.</li>
<li><strong>Skip it</strong> (for now) if nobody can monitor signature expiry or handle a KSK rollover. An expired signature takes the whole zone offline for validating resolvers, which is worse than no DNSSEC.</li>
</ul>
<h2 id="how-it-works">How it works <a class="anchor" data-pagefind-ignore href="#how-it-works" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Lives in</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>KSK (Key Signing Key)</td>
					<td>Your zone</td>
					<td>Signs the DNSKEY RRset (the zone&rsquo;s public keys)</td>
			</tr>
			<tr>
					<td>ZSK (Zone Signing Key)</td>
					<td>Your zone</td>
					<td>Signs all other records</td>
			</tr>
			<tr>
					<td>RRSIG records</td>
					<td>Your zone</td>
					<td>The signatures, one per record set</td>
			</tr>
			<tr>
					<td>NSEC / NSEC3</td>
					<td>Your zone</td>
					<td>Prove that a name or type does not exist</td>
			</tr>
			<tr>
					<td>DS record</td>
					<td>Parent zone</td>
					<td>Hash of your KSK; links your zone into the chain of trust</td>
			</tr>
	</tbody>
</table>
<p>The flow: resolver trusts the parent → parent&rsquo;s DS matches your KSK → KSK signs your DNSKEY set → ZSK signs your records → answer validated.</p>
<h3 id="key-signing-key-ksk">Key Signing Key (KSK) <a class="anchor" data-pagefind-ignore href="#key-signing-key-ksk" aria-label="Link to this section">#</a></h3>
<ul>
<li>Signs the DNSKEY RRset (the zone&rsquo;s public keys)</li>
<li>Longer lifetime (typically 1-2 years)</li>
<li>Larger key size for stronger security</li>
<li>Its hash (DS record) is published in the parent zone</li>
</ul>
<h3 id="zone-signing-key-zsk">Zone Signing Key (ZSK) <a class="anchor" data-pagefind-ignore href="#zone-signing-key-zsk" aria-label="Link to this section">#</a></h3>
<ul>
<li>Signs all other records in the zone</li>
<li>Shorter lifetime (typically 1-3 months)</li>
<li>Smaller key size for performance</li>
<li>Rolled more frequently</li>
</ul>
<p>The split exists because a KSK change needs your registrar (a new DS record), while a ZSK change does not. Keeping the KSK stable means you can roll the ZSK as often as you like without touching the parent.</p>
<h2 id="choosing-dnssec-algorithms">Choosing DNSSEC Algorithms <a class="anchor" data-pagefind-ignore href="#choosing-dnssec-algorithms" aria-label="Link to this section">#</a></h2>
<p>Modern BIND supports several algorithms:</p>
<table>
	<thead>
			<tr>
					<th>Algorithm</th>
					<th>Number</th>
					<th>Recommendation</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>RSASHA256</td>
					<td>8</td>
					<td>Good, widely supported</td>
			</tr>
			<tr>
					<td>RSASHA512</td>
					<td>10</td>
					<td>Good, wider margins</td>
			</tr>
			<tr>
					<td>ECDSAP256SHA256</td>
					<td>13</td>
					<td>Recommended, smaller keys</td>
			</tr>
			<tr>
					<td>ECDSAP384SHA384</td>
					<td>14</td>
					<td>Strong, larger signatures</td>
			</tr>
			<tr>
					<td>ED25519</td>
					<td>15</td>
					<td>Best, smallest signatures</td>
			</tr>
	</tbody>
</table>
<p>For new deployments, use <strong>ECDSAP256SHA256 (13)</strong> or <strong>ED25519 (15)</strong> for best performance and security. Smaller signatures keep responses under the UDP size limit.</p>
<h2 id="manual-signing-or-dnssec-policy">Manual signing or dnssec-policy? <a class="anchor" data-pagefind-ignore href="#manual-signing-or-dnssec-policy" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Approach</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Manual (<code>dnssec-keygen</code> + <code>dnssec-signzone</code>)</td>
					<td>Understanding the mechanics, or offline signing. You re-sign before signatures expire and run rollovers yourself.</td>
			</tr>
			<tr>
					<td><code>dnssec-policy</code> + inline signing</td>
					<td>Production. BIND generates keys, signs, re-signs and rolls the ZSK automatically.</td>
			</tr>
	</tbody>
</table>
<p>The manual steps below show what BIND automates. If you only want a working setup, skip to <a href="#automated-dnssec-with-dnssec-policy">Automated DNSSEC with dnssec-policy</a>.</p>
<h2 id="manual-dnssec-configuration">Manual DNSSEC Configuration <a class="anchor" data-pagefind-ignore href="#manual-dnssec-configuration" aria-label="Link to this section">#</a></h2>
<h3 id="generating-keys-manually">Generating Keys Manually <a class="anchor" data-pagefind-ignore href="#generating-keys-manually" aria-label="Link to this section">#</a></h3>
<p>First create a key directory that only BIND can read. The private keys in it can sign anything for your zone.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">mkdir -p /var/cache/bind/keys
</span></span><span class="line"><span class="cl">chown bind:bind /var/cache/bind/keys
</span></span><span class="line"><span class="cl">chmod <span class="m">700</span> /var/cache/bind/keys
</span></span></code></pre></div><p>Generate the KSK. <code>-f KSK</code> sets the KSK flag; <code>-n ZONE</code> marks it as a zone key.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nb">cd</span> /var/cache/bind/keys
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate KSK with ECDSAP256SHA256</span>
</span></span><span class="line"><span class="cl">dnssec-keygen -a ECDSAP256SHA256 -f KSK -n ZONE example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Or with RSA (2048-bit minimum, 4096 recommended for KSK)</span>
</span></span><span class="line"><span class="cl">dnssec-keygen -a RSASHA256 -b <span class="m">4096</span> -f KSK -n ZONE example.com
</span></span></code></pre></div><p>Generate the ZSK (same command, without <code>-f KSK</code>):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Generate ZSK with ECDSAP256SHA256</span>
</span></span><span class="line"><span class="cl">dnssec-keygen -a ECDSAP256SHA256 -n ZONE example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Or with RSA (2048-bit)</span>
</span></span><span class="line"><span class="cl">dnssec-keygen -a RSASHA256 -b <span class="m">2048</span> -n ZONE example.com
</span></span></code></pre></div><p>This creates two files per key:</p>
<ul>
<li><code>Kexample.com.+013+12345.key</code> - Public key (DNSKEY record)</li>
<li><code>Kexample.com.+013+12345.private</code> - Private key</li>
</ul>
<p>The <code>013</code> in the name is the algorithm number; <code>12345</code> is the key tag.</p>
<h3 id="manual-zone-signing">Manual Zone Signing <a class="anchor" data-pagefind-ignore href="#manual-zone-signing" aria-label="Link to this section">#</a></h3>
<p>Add the public keys to the zone with <code>$INCLUDE</code>, so the DNSKEY records are part of what gets signed:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-dns" data-lang="dns"><span class="line"><span class="cl"><span class="c">; /var/cache/bind/zones/db.example.com</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="na">$TTL</span><span class="w"> </span><span class="sc">86400</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="na">$INCLUDE</span><span class="w"> </span><span class="err">/var/cache/bind/keys/</span><span class="nc">Kexample.com.</span><span class="err">+</span><span class="sc">013</span><span class="err">+</span><span class="sc">12345</span><span class="err">.key</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="na">$INCLUDE</span><span class="w"> </span><span class="err">/var/cache/bind/keys/</span><span class="nc">Kexample.com.</span><span class="err">+</span><span class="sc">013</span><span class="err">+</span><span class="sc">67890</span><span class="err">.key</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">@</span><span class="w">   </span><span class="k">IN</span><span class="w">  </span><span class="k">SOA</span><span class="w"> </span><span class="py">ns1.example.com. admin.example.com. </span><span class="p">(</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="sc">2024011001</span><span class="w">  </span><span class="c">; Serial</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="sc">3600</span><span class="w">        </span><span class="c">; Refresh</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="sc">1800</span><span class="w">        </span><span class="c">; Retry</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="sc">604800</span><span class="w">      </span><span class="c">; Expire</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="sc">86400</span><span class="w"> </span><span class="p">)</span><span class="w">     </span><span class="c">; Minimum TTL</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">IN</span><span class="w">  </span><span class="k">NS</span><span class="w">  </span><span class="py">ns1.example.com.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">IN</span><span class="w">  </span><span class="k">NS</span><span class="w">  </span><span class="py">ns2.example.com.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">IN</span><span class="w">  </span><span class="k">MX</span><span class="w">  </span><span class="sc">10</span><span class="w"> </span><span class="py">mail.example.com.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">IN</span><span class="w">  </span><span class="k">A</span><span class="w">   </span><span class="mi">192.168.1.10</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">ns1</span><span class="w"> </span><span class="k">IN</span><span class="w">  </span><span class="k">A</span><span class="w">   </span><span class="mi">192.168.1.1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">ns2</span><span class="w"> </span><span class="k">IN</span><span class="w">  </span><span class="k">A</span><span class="w">   </span><span class="mi">192.168.1.2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">mail</span><span class="w"> </span><span class="k">IN</span><span class="w"> </span><span class="k">A</span><span class="w">   </span><span class="mi">192.168.1.20</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">www</span><span class="w"> </span><span class="k">IN</span><span class="w">  </span><span class="k">A</span><span class="w">   </span><span class="mi">192.168.1.10</span><span class="w">
</span></span></span></code></pre></div><p>Then sign the zone:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Sign zone with NSEC3 (no salt, 0 iterations as per RFC 9276)</span>
</span></span><span class="line"><span class="cl">dnssec-signzone -3 - <span class="se">\
</span></span></span><span class="line"><span class="cl">    -N INCREMENT -o example.com -t <span class="se">\
</span></span></span><span class="line"><span class="cl">    -K /var/cache/bind/keys <span class="se">\
</span></span></span><span class="line"><span class="cl">    /var/cache/bind/zones/db.example.com
</span></span></code></pre></div><ul>
<li><code>-3 -</code>: use NSEC3 with no salt.</li>
<li><code>-N INCREMENT</code>: increase the SOA serial so slave servers pick up the signed version.</li>
<li><code>-o example.com</code>: the zone origin.</li>
<li><code>-t</code>: print signing statistics.</li>
<li><code>-K</code>: where to find the keys.</li>
</ul>
<p>This creates <code>db.example.com.signed</code> containing:</p>
<ul>
<li>RRSIG records (signatures)</li>
<li>NSEC3 records (authenticated denial of existence)</li>
<li>NSEC3PARAM record</li>
</ul>
<p>Point the zone&rsquo;s <code>file</code> at the <code>.signed</code> file. You have to repeat the signing run before the signatures expire.</p>
<h2 id="automated-dnssec-with-dnssec-policy">Automated DNSSEC with dnssec-policy <a class="anchor" data-pagefind-ignore href="#automated-dnssec-with-dnssec-policy" aria-label="Link to this section">#</a></h2>
<p>BIND 9.16+ supports automatic key management with <code>dnssec-policy</code>. This is the recommended approach: you describe the keys and timings once, and BIND does the rest.</p>
<h3 id="define-dnssec-policies">Define DNSSEC Policies <a class="anchor" data-pagefind-ignore href="#define-dnssec-policies" aria-label="Link to this section">#</a></h3>
<p>A policy says which keys to use, how long they live and how long signatures stay valid. Define it once and reuse it for many zones.</p>
<pre tabindex="0"><code class="language-named" data-lang="named">// /etc/bind/named.conf.options

dnssec-policy &#34;standard&#34; {
    // Key algorithm and parameters
    keys {
        // KSK: ECDSA P-256, unlimited lifetime (manual rollover)
        ksk key-directory lifetime unlimited algorithm ecdsap256sha256;
        // ZSK: ECDSA P-256, 90-day lifetime (auto rollover)
        zsk key-directory lifetime 90d algorithm ecdsap256sha256;
    };

    // Timing parameters
    dnskey-ttl 3600;              // TTL for DNSKEY records
    publish-safety 1h;             // Safety margin for publishing
    retire-safety 1h;              // Safety margin for retiring
    purge-keys 90d;                // Remove old keys after 90 days

    // Signature parameters
    signatures-refresh 5d;         // Re-sign 5 days before expiry
    signatures-validity 14d;       // Signatures valid for 14 days
    signatures-validity-dnskey 14d;

    // NSEC3 parameters (authenticated denial)
    nsec3param iterations 0 optout no salt-length 0;

    // Key storage: key-directory is not valid inside dnssec-policy,
    // set it in the zone (or options) statement instead
};

// More conservative policy for critical zones
dnssec-policy &#34;critical&#34; {
    keys {
        ksk key-directory lifetime unlimited algorithm ecdsap384sha384;
        zsk key-directory lifetime 30d algorithm ecdsap384sha384;
    };
    dnskey-ttl 1800;
    signatures-refresh 3d;
    signatures-validity 7d;
    signatures-validity-dnskey 7d;
    nsec3param iterations 0 optout no salt-length 0;
};

// Default policy (built-in)
// Uses a single ECDSAP256SHA256 CSK with unlimited lifetime, NSEC
</code></pre><p>What the key settings do:</p>
<table>
	<thead>
			<tr>
					<th>Setting</th>
					<th>What it does</th>
					<th>When to change it</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>ksk ... lifetime unlimited</code></td>
					<td>KSK never rolls automatically</td>
					<td>Keep; KSK rolls need the registrar</td>
			</tr>
			<tr>
					<td><code>zsk ... lifetime 90d</code></td>
					<td>ZSK is replaced every 90 days</td>
					<td>Shorter for critical zones</td>
			</tr>
			<tr>
					<td><code>dnskey-ttl</code></td>
					<td>TTL of the DNSKEY records</td>
					<td>Lower if you want faster rollovers</td>
			</tr>
			<tr>
					<td><code>publish-safety</code> / <code>retire-safety</code></td>
					<td>Extra margin before a new key is used and after an old key is retired</td>
					<td>Raise if caches upstream are slow</td>
			</tr>
			<tr>
					<td><code>purge-keys</code></td>
					<td>Delete old key files this long after removal</td>
					<td>Keep long enough for troubleshooting</td>
			</tr>
			<tr>
					<td><code>signatures-validity</code></td>
					<td>How long each signature is valid</td>
					<td>Shorter = less replay window, more re-signing</td>
			</tr>
			<tr>
					<td><code>signatures-refresh</code></td>
					<td>Re-sign this long before expiry</td>
					<td>Must stay well below the validity</td>
			</tr>
			<tr>
					<td><code>nsec3param iterations 0 ... salt-length 0</code></td>
					<td>NSEC3 with the RFC 9276 values</td>
					<td>Keep</td>
			</tr>
	</tbody>
</table>
<p>The <code>critical</code> policy uses a stronger algorithm, a 30-day ZSK and shorter signature validity. <code>dnssec-policy default</code> uses BIND&rsquo;s built-in policy, described in the last comment of the block.</p>
<h3 id="apply-policy-to-zones">Apply Policy to Zones <a class="anchor" data-pagefind-ignore href="#apply-policy-to-zones" aria-label="Link to this section">#</a></h3>
<p>Attach a policy to each zone with <code>dnssec-policy</code>. The zone file stays as you wrote it.</p>
<pre tabindex="0"><code class="language-named" data-lang="named">// /etc/bind/named.conf.local

zone &#34;example.com&#34; {
    type primary;
    file &#34;/var/cache/bind/zones/db.example.com&#34;;
    dnssec-policy &#34;standard&#34;;
    inline-signing yes;  // Sign dynamically, keep unsigned source
    key-directory &#34;/var/cache/bind/keys&#34;;
};

zone &#34;critical.example.com&#34; {
    type primary;
    file &#34;/var/cache/bind/zones/db.critical.example.com&#34;;
    dnssec-policy &#34;critical&#34;;
    inline-signing yes;
    key-directory &#34;/var/cache/bind/keys&#34;;
};
</code></pre><ul>
<li><code>inline-signing yes</code>: BIND keeps your unsigned file and serves a signed copy.</li>
<li><code>key-directory</code>: where BIND creates and reads the keys for this zone.</li>
</ul>
<h3 id="inline-signing">Inline Signing <a class="anchor" data-pagefind-ignore href="#inline-signing" aria-label="Link to this section">#</a></h3>
<p>With <code>inline-signing yes</code>, BIND:</p>
<ul>
<li>Keeps your original zone file unchanged</li>
<li>Creates a signed version automatically</li>
<li>Re-signs when signatures approach expiry</li>
<li>Handles key rollovers automatically</li>
</ul>
<p>You keep editing the normal zone file and reloading; BIND signs the changes.</p>
<h2 id="publishing-the-ds-record">Publishing the DS Record <a class="anchor" data-pagefind-ignore href="#publishing-the-ds-record" aria-label="Link to this section">#</a></h2>
<p>A signed zone is not trusted until the parent zone holds its DS record. Until then, validating resolvers treat it as unsigned.</p>
<h3 id="generate-ds-record">Generate DS Record <a class="anchor" data-pagefind-ignore href="#generate-ds-record" aria-label="Link to this section">#</a></h3>
<p><code>dnssec-dsfromkey</code> computes the DS record from the KSK. <code>-2</code> selects SHA-256:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Generate DS records from your KSK</span>
</span></span><span class="line"><span class="cl">dnssec-dsfromkey -2 /var/cache/bind/keys/Kexample.com.+013+12345.key
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Output:</span>
</span></span><span class="line"><span class="cl"><span class="c1"># example.com. IN DS 12345 13 2 E2D3C916F6DED0ED3D9A8E6C1C0A2ED7...</span>
</span></span></code></pre></div><p>The DS record contains:</p>
<ul>
<li>Key tag (12345)</li>
<li>Algorithm (13 = ECDSAP256SHA256)</li>
<li>Digest type (2 = SHA-256)</li>
<li>Digest (hash of the KSK)</li>
</ul>
<h3 id="submit-ds-record-to-registrar">Submit DS Record to Registrar <a class="anchor" data-pagefind-ignore href="#submit-ds-record-to-registrar" aria-label="Link to this section">#</a></h3>
<p>For domains registered with a registrar:</p>
<ol>
<li>Log into your registrar&rsquo;s control panel</li>
<li>Find DNS/DNSSEC settings</li>
<li>Add the DS record with:
<ul>
<li>Key Tag: 12345</li>
<li>Algorithm: 13</li>
<li>Digest Type: 2</li>
<li>Digest: (the hash value)</li>
</ul>
</li>
</ol>
<p>For subzones under your control, add the DS record to the parent zone:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-dns" data-lang="dns"><span class="line"><span class="cl"><span class="c">; In parent zone</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">subdomain</span><span class="w"> </span><span class="k">IN</span><span class="w"> </span><span class="k">DS</span><span class="w"> </span><span class="sc">12345</span><span class="w"> </span><span class="sc">13</span><span class="w"> </span><span class="sc">2</span><span class="w"> </span><span class="py">E2D3C916F6DED0ED3D9A8E6C1C0A2ED7...</span><span class="w">
</span></span></span></code></pre></div><h2 id="nsec-vs-nsec3">NSEC vs NSEC3 <a class="anchor" data-pagefind-ignore href="#nsec-vs-nsec3" aria-label="Link to this section">#</a></h2>
<p>A signed zone must also prove that a name does <em>not</em> exist. NSEC and NSEC3 do this in different ways:</p>
<table>
	<thead>
			<tr>
					<th></th>
					<th>NSEC</th>
					<th>NSEC3</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>How</td>
					<td>Links each name to the next one, in clear text</td>
					<td>Links hashed names</td>
			</tr>
			<tr>
					<td>Zone walking</td>
					<td>Possible: anyone can list all names</td>
					<td>Prevented</td>
			</tr>
			<tr>
					<td>Cost</td>
					<td>Simpler, smaller responses</td>
					<td>Slightly larger responses, more CPU</td>
			</tr>
			<tr>
					<td>In dnssec-policy</td>
					<td>Default (no <code>nsec3param</code>)</td>
					<td>Add <code>nsec3param</code></td>
			</tr>
	</tbody>
</table>
<h3 id="nsec-original">NSEC (Original) <a class="anchor" data-pagefind-ignore href="#nsec-original" aria-label="Link to this section">#</a></h3>
<pre tabindex="0"><code class="language-named" data-lang="named">// Enable NSEC (default)
dnssec-policy &#34;nsec-policy&#34; {
    keys {
        ksk lifetime unlimited algorithm ecdsap256sha256;
        zsk lifetime 90d algorithm ecdsap256sha256;
    };
    // No nsec3param = use NSEC
};
</code></pre><h3 id="nsec3-recommended">NSEC3 (Recommended) <a class="anchor" data-pagefind-ignore href="#nsec3-recommended" aria-label="Link to this section">#</a></h3>
<pre tabindex="0"><code class="language-named" data-lang="named">// Enable NSEC3
dnssec-policy &#34;nsec3-policy&#34; {
    keys {
        ksk lifetime unlimited algorithm ecdsap256sha256;
        zsk lifetime 90d algorithm ecdsap256sha256;
    };
    // NSEC3 parameters
    // iterations: 0 recommended (RFC 9276)
    // optout: no (sign all records)
    // salt-length: 0 recommended (RFC 9276)
    nsec3param iterations 0 optout no salt-length 0;
};
</code></pre><p>RFC 9276 recommends 0 iterations and no salt: extra iterations cost resolvers CPU without adding real protection.</p>
<h2 id="key-rollover-procedures">Key Rollover Procedures <a class="anchor" data-pagefind-ignore href="#key-rollover-procedures" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Key</th>
					<th>Rollover</th>
					<th>Parent involved</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>ZSK</td>
					<td>Automatic with <code>dnssec-policy</code></td>
					<td>No</td>
			</tr>
			<tr>
					<td>KSK</td>
					<td>Manual, triggered by you</td>
					<td>Yes, new DS record</td>
			</tr>
	</tbody>
</table>
<h3 id="automatic-zsk-rollover">Automatic ZSK Rollover <a class="anchor" data-pagefind-ignore href="#automatic-zsk-rollover" aria-label="Link to this section">#</a></h3>
<p>With <code>dnssec-policy</code>, ZSK rollovers happen automatically. Check the key states and the next scheduled rollover:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check key states and the next scheduled rollover</span>
</span></span><span class="line"><span class="cl">rndc dnssec -status example.com
</span></span></code></pre></div><p><code>rndc signing -list</code> does not work for zones that use <code>dnssec-policy</code>; BIND answers &ldquo;zone uses dnssec-policy, use rndc dnssec command instead&rdquo;.</p>
<h3 id="manual-ksk-rollover-double-ds-method">Manual KSK Rollover (Double-DS Method) <a class="anchor" data-pagefind-ignore href="#manual-ksk-rollover-double-ds-method" aria-label="Link to this section">#</a></h3>
<p>A KSK rollover changes the DS record in the parent, so you coordinate it with the registrar. With the double-DS method the old and new DS are both published for a while, so validation never breaks.</p>
<p><strong>Step 1: Generate new KSK</strong></p>
<p><code>rndc dnssec -rollover</code> starts the rollover of an existing key under <code>dnssec-policy</code>; <code>dnssec-keygen</code> is the manual alternative.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Generate successor KSK</span>
</span></span><span class="line"><span class="cl">rndc dnssec -rollover -key <span class="m">12345</span> example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Or manually</span>
</span></span><span class="line"><span class="cl">dnssec-keygen -a ECDSAP256SHA256 -f KSK -n ZONE example.com
</span></span></code></pre></div><p><strong>Step 2: Add new DS to parent</strong></p>
<p>Compute the DS for the new key and add it at the registrar next to the old one:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Generate DS for new key</span>
</span></span><span class="line"><span class="cl">dnssec-dsfromkey /var/cache/bind/keys/Kexample.com.+013+NEW_ID.key
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Submit new DS to registrar (keep old DS)</span>
</span></span></code></pre></div><p><strong>Step 3: Wait for propagation</strong></p>
<p>Wait at least 2x the TTL of the DS record in the parent zone.</p>
<p><strong>Step 4: Complete rollover</strong></p>
<p>BIND does not watch your registrar; tell it when each DS change is live. Run the first command once the new DS is published. Then remove the old DS at your registrar and run the second command.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Tell BIND the new DS is published in the parent</span>
</span></span><span class="line"><span class="cl">rndc dnssec -checkds -key NEW_ID published example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># After TTL expires, remove old DS from parent, then tell BIND it is withdrawn</span>
</span></span><span class="line"><span class="cl">rndc dnssec -checkds -key <span class="m">12345</span> withdrawn example.com
</span></span></code></pre></div><h2 id="monitoring-dnssec-health">Monitoring DNSSEC Health <a class="anchor" data-pagefind-ignore href="#monitoring-dnssec-health" aria-label="Link to this section">#</a></h2>
<h3 id="check-zone-signatures">Check Zone Signatures <a class="anchor" data-pagefind-ignore href="#check-zone-signatures" aria-label="Link to this section">#</a></h3>
<p>Expired signatures are the most common DNSSEC outage. This script reads the expiry of the SOA signature and warns when fewer than <code>WARN_DAYS</code> remain:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># check-dnssec.sh - Monitor DNSSEC signature expiry</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">ZONE</span><span class="o">=</span><span class="s2">&#34;example.com&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">WARN_DAYS</span><span class="o">=</span><span class="m">7</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Get signature expiry from zone</span>
</span></span><span class="line"><span class="cl"><span class="nv">EXPIRY</span><span class="o">=</span><span class="k">$(</span>dig +dnssec @localhost <span class="nv">$ZONE</span> SOA <span class="p">|</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    grep RRSIG <span class="p">|</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    awk <span class="s1">&#39;{print $9}&#39;</span> <span class="p">|</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    head -1<span class="k">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">if</span> <span class="o">[</span> -n <span class="s2">&#34;</span><span class="nv">$EXPIRY</span><span class="s2">&#34;</span> <span class="o">]</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># Parse DNSSEC timestamp (YYYYMMDDHHMMSS)</span>
</span></span><span class="line"><span class="cl">    <span class="nv">EXPIRY_EPOCH</span><span class="o">=</span><span class="k">$(</span>date -d <span class="s2">&#34;</span><span class="si">${</span><span class="nv">EXPIRY</span><span class="p">:</span><span class="nv">0</span><span class="p">:</span><span class="nv">8</span><span class="si">}</span><span class="s2"> </span><span class="si">${</span><span class="nv">EXPIRY</span><span class="p">:</span><span class="nv">8</span><span class="p">:</span><span class="nv">2</span><span class="si">}</span><span class="s2">:</span><span class="si">${</span><span class="nv">EXPIRY</span><span class="p">:</span><span class="nv">10</span><span class="p">:</span><span class="nv">2</span><span class="si">}</span><span class="s2">:</span><span class="si">${</span><span class="nv">EXPIRY</span><span class="p">:</span><span class="nv">12</span><span class="p">:</span><span class="nv">2</span><span class="si">}</span><span class="s2">&#34;</span> +%s 2&gt;/dev/null<span class="k">)</span>
</span></span><span class="line"><span class="cl">    <span class="nv">NOW_EPOCH</span><span class="o">=</span><span class="k">$(</span>date +%s<span class="k">)</span>
</span></span><span class="line"><span class="cl">    <span class="nv">DAYS_LEFT</span><span class="o">=</span><span class="k">$((</span> <span class="o">(</span>EXPIRY_EPOCH <span class="o">-</span> NOW_EPOCH<span class="o">)</span> <span class="o">/</span> <span class="m">86400</span> <span class="k">))</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="nb">echo</span> <span class="s2">&#34;Zone: </span><span class="nv">$ZONE</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="nb">echo</span> <span class="s2">&#34;Signature expires: </span><span class="nv">$EXPIRY</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="nb">echo</span> <span class="s2">&#34;Days remaining: </span><span class="nv">$DAYS_LEFT</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="o">[</span> <span class="nv">$DAYS_LEFT</span> -lt <span class="nv">$WARN_DAYS</span> <span class="o">]</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">        <span class="nb">echo</span> <span class="s2">&#34;WARNING: Signatures expiring soon!&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="nb">exit</span> <span class="m">1</span>
</span></span><span class="line"><span class="cl">    <span class="k">fi</span>
</span></span><span class="line"><span class="cl"><span class="k">else</span>
</span></span><span class="line"><span class="cl">    <span class="nb">echo</span> <span class="s2">&#34;ERROR: Could not retrieve DNSSEC signatures for </span><span class="nv">$ZONE</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="nb">exit</span> <span class="m">2</span>
</span></span><span class="line"><span class="cl"><span class="k">fi</span>
</span></span></code></pre></div><p>With <code>dnssec-policy</code>, signatures are refreshed automatically, so a warning here means re-signing has stopped.</p>
<h3 id="verify-chain-of-trust">Verify Chain of Trust <a class="anchor" data-pagefind-ignore href="#verify-chain-of-trust" aria-label="Link to this section">#</a></h3>
<p>Check the full chain from outside, then compare the parent&rsquo;s DS with your key and verify the signed zone file:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Full chain verification</span>
</span></span><span class="line"><span class="cl">delv @8.8.8.8 example.com SOA +rtrace
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check DS record matches</span>
</span></span><span class="line"><span class="cl">dig DS example.com @parent-ns.tld
</span></span><span class="line"><span class="cl">dnssec-dsfromkey /var/cache/bind/keys/Kexample.com.+013+12345.key
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Verify signatures</span>
</span></span><span class="line"><span class="cl">dnssec-verify -o example.com /var/cache/bind/zones/db.example.com.signed
</span></span></code></pre></div><ul>
<li><code>delv ... +rtrace</code>: validates through a public resolver, like your users&rsquo; resolvers would.</li>
<li><code>dnssec-verify</code>: checks that every record in the signed file has valid signatures.</li>
</ul>
<h3 id="online-validation-tools">Online Validation Tools <a class="anchor" data-pagefind-ignore href="#online-validation-tools" aria-label="Link to this section">#</a></h3>
<p>Use these services to verify your DNSSEC deployment:</p>
<ul>
<li>DNSViz: <a href="https://dnsviz.net/" rel="noopener">https://dnsviz.net/</a></li>
<li>Verisign DNSSEC Analyzer: <a href="https://dnssec-analyzer.verisignlabs.com/" rel="noopener">https://dnssec-analyzer.verisignlabs.com/</a></li>
<li>SIDN DNSSEC Test: <a href="https://check.sidnlabs.nl/" rel="noopener">https://check.sidnlabs.nl/</a></li>
</ul>
<h2 id="complete-configuration-example">Complete Configuration Example <a class="anchor" data-pagefind-ignore href="#complete-configuration-example" aria-label="Link to this section">#</a></h2>
<p>Here&rsquo;s a production-ready DNSSEC configuration. The options and policy go in <code>named.conf.options</code>:</p>
<pre tabindex="0"><code class="language-named" data-lang="named">// /etc/bind/named.conf.options

options {
    directory &#34;/var/cache/bind&#34;;
    
    // DNSSEC validation for the server&#39;s own recursive lookups
    dnssec-validation auto;
    
    // Key and managed-keys directory (both must exist, named exits otherwise)
    key-directory &#34;/var/cache/bind/keys&#34;;
    managed-keys-directory &#34;/var/cache/bind/managed-keys&#34;;
    
    // Logging
    querylog yes;
};

// Standard DNSSEC policy
dnssec-policy &#34;production&#34; {
    keys {
        ksk key-directory lifetime unlimited algorithm ecdsap256sha256;
        zsk key-directory lifetime P90D algorithm ecdsap256sha256;
    };
    
    // Timing
    dnskey-ttl PT1H;
    publish-safety PT1H;
    retire-safety PT1H;
    purge-keys P90D;
    
    // Signatures
    signatures-refresh P5D;
    signatures-validity P14D;
    signatures-validity-dnskey P14D;
    
    // NSEC3 (RFC 9276 recommendations)
    nsec3param iterations 0 optout no salt-length 0;
};

logging {
    channel dnssec_log {
        file &#34;/var/log/named/dnssec.log&#34; versions 3 size 10m;
        severity info;
        print-time yes;
        print-severity yes;
    };
    category dnssec { dnssec_log; };
};
</code></pre><ul>
<li><code>key-directory</code> / <code>managed-keys-directory</code>: both directories must exist, or <code>named</code> will not start.</li>
<li>The policy values use ISO 8601 durations (<code>P90D</code>, <code>PT1H</code>); they mean the same as <code>90d</code> and <code>1h</code> above.</li>
</ul>
<p>The zones go in <code>named.conf.local</code>, with the reverse zone signed too:</p>
<pre tabindex="0"><code class="language-named" data-lang="named">// /etc/bind/named.conf.local

zone &#34;example.com&#34; {
    type primary;
    file &#34;/var/cache/bind/zones/db.example.com&#34;;
    dnssec-policy &#34;production&#34;;
    inline-signing yes;
    
    // Allow zone transfers to secondaries
    // (key &#34;transfer-key&#34; must be defined, see the RNDC and TSIG post)
    allow-transfer { key &#34;transfer-key&#34;; };
    also-notify { 192.168.1.2; };
};

zone &#34;1.168.192.in-addr.arpa&#34; {
    type primary;
    file &#34;/var/cache/bind/zones/db.192.168.1&#34;;
    dnssec-policy &#34;production&#34;;
    inline-signing yes;
    allow-transfer { key &#34;transfer-key&#34;; };
};
</code></pre><ul>
<li><code>allow-transfer { key &quot;transfer-key&quot;; }</code>: only servers with the TSIG key may transfer the zone. They receive the signed version.</li>
<li><code>also-notify</code>: tell the slave server at 192.168.1.2 about changes, including re-signing.</li>
</ul>
<h2 id="troubleshooting-dnssec">Troubleshooting DNSSEC <a class="anchor" data-pagefind-ignore href="#troubleshooting-dnssec" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Cause</th>
					<th>Fix</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Signatures expired</td>
					<td>Re-signing stopped</td>
					<td>Check <code>rndc dnssec -status</code>, force <code>rndc sign</code></td>
			</tr>
			<tr>
					<td>SERVFAIL after DS change</td>
					<td>DS at parent does not match the KSK</td>
					<td>Compare DS records</td>
			</tr>
			<tr>
					<td>Zone not signed</td>
					<td>Key files missing or unreadable</td>
					<td>Check permissions</td>
			</tr>
			<tr>
					<td>Zone won&rsquo;t load</td>
					<td>Syntax error in config or zone</td>
					<td><code>named-checkconf</code>, <code>named-checkzone</code></td>
			</tr>
	</tbody>
</table>
<h3 id="common-issues">Common Issues <a class="anchor" data-pagefind-ignore href="#common-issues" aria-label="Link to this section">#</a></h3>
<p><strong>Signatures expired:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check key and signing state</span>
</span></span><span class="line"><span class="cl">rndc dnssec -status example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Force re-signing</span>
</span></span><span class="line"><span class="cl">rndc sign example.com
</span></span></code></pre></div><p><strong>DS record mismatch:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Compare DS records</span>
</span></span><span class="line"><span class="cl">dig DS example.com @parent-ns
</span></span><span class="line"><span class="cl">dnssec-dsfromkey Kexample.com.+013+12345.key
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Ensure key tag, algorithm, and digest match</span>
</span></span></code></pre></div><p><strong>Key not found:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check key files exist and permissions</span>
</span></span><span class="line"><span class="cl">ls -la /var/cache/bind/keys/
</span></span><span class="line"><span class="cl">chown bind:bind /var/cache/bind/keys/*
</span></span><span class="line"><span class="cl">chmod <span class="m">600</span> /var/cache/bind/keys/*.private
</span></span></code></pre></div><p><strong>Zone won&rsquo;t load:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check configuration</span>
</span></span><span class="line"><span class="cl">named-checkconf
</span></span><span class="line"><span class="cl">named-checkzone example.com /var/cache/bind/zones/db.example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check logs</span>
</span></span><span class="line"><span class="cl">tail -f /var/log/named/dnssec.log
</span></span></code></pre></div><h2 id="security-best-practices">Security Best Practices <a class="anchor" data-pagefind-ignore href="#security-best-practices" aria-label="Link to this section">#</a></h2>
<ol>
<li><strong>Protect private keys</strong> - Use proper file permissions (600) and consider HSM for high-security deployments</li>
<li><strong>Monitor signature expiry</strong> - Set up alerts for signatures approaching expiry</li>
<li><strong>Test rollovers</strong> - Practice key rollovers in a test environment first</li>
<li><strong>Use NSEC3</strong> - Prevents zone enumeration attacks</li>
<li><strong>Keep BIND updated</strong> - Security fixes often affect DNSSEC</li>
<li><strong>Document procedures</strong> - Especially for manual KSK rollovers</li>
<li><strong>Backup keys securely</strong> - Store encrypted backups offline</li>
</ol>
<h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub: <a href="https://github.com/pderuiter/blog-bind-dnssec-signing" rel="noopener">pderuiter/blog-bind-dnssec-signing</a>. It creates an Ubuntu 24.04 VM on Proxmox and sets up the complete configuration from this post (the <code>production</code> dnssec-policy, inline-signed forward and reverse zones, TSIG-protected transfers and the expiry check script); run <code>terraform apply</code>, then <code>ansible-playbook site.yml</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>DNSSEC on authoritative servers completes the chain of trust for your domains. <code>dnssec-policy</code> with inline signing automates most of the work; monitoring makes sure your zones stay signed.</p>
<p>Key takeaways:</p>
<ul>
<li>Use ECDSAP256SHA256 or ED25519 algorithms</li>
<li>Enable inline-signing for automatic signature maintenance</li>
<li>Use NSEC3 to prevent zone enumeration</li>
<li>Monitor signature expiry proactively</li>
<li>Plan and test key rollovers carefully</li>
</ul>
<p>The next post will cover Response Policy Zones (RPZ), using BIND to block malicious domains and enforce DNS-based security policies.</p>
]]></content:encoded></item><item><title>Implementing DNS-Based Security with BIND Response Policy Zones</title><link>https://blog.bsdserver.nl/implementing-dns-based-security-with-bind-response-policy-zones/</link><guid isPermaLink="false">693b6d5379eb54000160a580</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:18:11 +0000</pubDate><description>Response Policy Zones (RPZ) provide DNS-level security by allowing you to override DNS responses for specific domains.</description><category>BIND</category><category>DNS</category><category>Response Policy Zones</category><category>Security</category><category>Malware</category><category>Linux</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/bind-rpz.png" medium="image"/><content:encoded><![CDATA[<p>Response Policy Zones (RPZ) provide DNS-level security by allowing you to override DNS responses for specific domains. Malware, phishing and tracking all start with a DNS lookup; if the lookup fails, the connection never happens.</p>
<p>This post sets up RPZ on a BIND recursive resolver. It covers the policy actions and triggers, external blocklists with automatic updates, a block page, whitelisting and logging.</p>
<h2 id="why-rpz">Why RPZ? <a class="anchor" data-pagefind-ignore href="#why-rpz" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>One control point</strong>: every device using the resolver is protected, including IoT devices and guests you cannot install software on.</li>
<li><strong>Blocks before the connection</strong>: the client never gets an address for a blocked domain.</li>
<li><strong>Standard format</strong>: blocklists are ordinary DNS zones; they can be transferred between servers like any zone.</li>
<li><strong>Visibility</strong>: RPZ logs show which client looked up which blocked domain.</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> on resolvers you control, to block known-bad domains, ads or trackers network-wide.</li>
<li><strong>Skip it</strong> on authoritative-only servers: RPZ only applies to recursive queries. It also cannot help clients that bypass your resolver (hard-coded DNS servers, DNS over HTTPS).</li>
</ul>
<h2 id="how-rpz-works">How RPZ Works <a class="anchor" data-pagefind-ignore href="#how-rpz-works" aria-label="Link to this section">#</a></h2>
<p>RPZ is a zone loaded by the resolver. Each record in it is a rule: the owner name says what to match (the trigger), the record data says what to answer instead (the action).</p>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>BIND resolver</td>
					<td>Your DNS server</td>
					<td>Resolves queries and applies the policy zones</td>
			</tr>
			<tr>
					<td>RPZ zones</td>
					<td>Same server (local file or transferred)</td>
					<td>Hold the rules</td>
			</tr>
			<tr>
					<td>Update script</td>
					<td>Same server (cron)</td>
					<td>Converts external blocklists into an RPZ zone</td>
			</tr>
			<tr>
					<td>Block page (optional)</td>
					<td>A web server</td>
					<td>Explains to users why a site is blocked</td>
			</tr>
	</tbody>
</table>
<p>The flow: client query → BIND checks the RPZ zones → match: rewritten answer and a log line → no match: normal resolution.</p>
<p>The rewritten answer can be:</p>
<table>
	<thead>
			<tr>
					<th>Action</th>
					<th>Client sees</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>NXDOMAIN</td>
					<td>Domain doesn&rsquo;t exist</td>
			</tr>
			<tr>
					<td>NODATA</td>
					<td>Domain exists but has no records of the requested type</td>
			</tr>
			<tr>
					<td>Custom IP</td>
					<td>An address of your choice: walled garden or block page</td>
			</tr>
			<tr>
					<td>CNAME</td>
					<td>Redirect to another domain</td>
			</tr>
			<tr>
					<td>Passthru</td>
					<td>The real answer (overrides more general rules)</td>
			</tr>
			<tr>
					<td>Drop</td>
					<td>No response at all</td>
			</tr>
	</tbody>
</table>
<h2 id="enabling-rpz-in-bind">Enabling RPZ in BIND <a class="anchor" data-pagefind-ignore href="#enabling-rpz-in-bind" aria-label="Link to this section">#</a></h2>
<h3 id="basic-configuration">Basic Configuration <a class="anchor" data-pagefind-ignore href="#basic-configuration" aria-label="Link to this section">#</a></h3>
<p>Two parts: the <code>response-policy</code> statement in <code>options</code> lists the policy zones, and each policy zone is a normal zone definition.</p>
<pre tabindex="0"><code>options {
    directory &#34;/var/named&#34;;
    recursion yes;
    allow-recursion { trusted; };
    
    response-policy {
        zone &#34;rpz.local&#34;;
    } qname-wait-recurse no;
};

zone &#34;rpz.local&#34; {
    type primary;
    file &#34;/var/named/rpz/rpz.local.zone&#34;;
    allow-query { none; };
    allow-transfer { none; };
};
</code></pre><ul>
<li><code>allow-query { none; }</code>: clients cannot query the policy zone directly; it is only used internally.</li>
<li><code>allow-transfer { none; }</code>: nobody can download your rules.</li>
</ul>
<p><code>qname-wait-recurse no</code> lets BIND apply QNAME rules without first resolving the real name. With the default (<code>yes</code>), a blocked domain whose own name servers are broken (common for malware domains) returns SERVFAIL instead of your block-page answer.</p>
<h3 id="creating-the-rpz-zone-file">Creating the RPZ Zone File <a class="anchor" data-pagefind-ignore href="#creating-the-rpz-zone-file" aria-label="Link to this section">#</a></h3>
<p>The zone needs a SOA and NS record like any zone; the NS is never used. The rules follow. Owner names have no trailing dot; BIND reads <code>malicious-site.com</code> as a rule for the domain malicious-site.com.</p>
<pre tabindex="0"><code>; /var/named/rpz/rpz.local.zone
$TTL 300
@   IN  SOA localhost. admin.localhost. (
        2024010101  ; Serial
        3600        ; Refresh
        1800        ; Retry
        604800      ; Expire
        300 )       ; Minimum TTL

    IN  NS  localhost.

; Block malicious-site.com (return NXDOMAIN)
malicious-site.com          CNAME   .
*.malicious-site.com        CNAME   .

; Block tracking domain (return NODATA)
tracker.example.com         CNAME   *.

; Redirect phishing site to block page
phishing-site.com           A       192.168.1.100
*.phishing-site.com         A       192.168.1.100

; Allow specific subdomain (passthru)
legit.blocked-domain.com    CNAME   rpz-passthru.

; Block entire domain but redirect to info page
bad-domain.com              CNAME   blocked.example.com.
</code></pre><h2 id="rpz-policy-actions">RPZ Policy Actions <a class="anchor" data-pagefind-ignore href="#rpz-policy-actions" aria-label="Link to this section">#</a></h2>
<p>The action is encoded in the record data. Pick the one that matches what the client should see:</p>
<table>
	<thead>
			<tr>
					<th>Action</th>
					<th>Record</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>NXDOMAIN</td>
					<td><code>CNAME .</code></td>
					<td>Default blocking</td>
			</tr>
			<tr>
					<td>NODATA</td>
					<td><code>CNAME *.</code></td>
					<td>Block a name without claiming it does not exist</td>
			</tr>
			<tr>
					<td>Local data</td>
					<td><code>A</code>, <code>AAAA</code> or <code>CNAME</code> to your host</td>
					<td>Block page or walled garden</td>
			</tr>
			<tr>
					<td>Passthru</td>
					<td><code>CNAME rpz-passthru.</code></td>
					<td>Exceptions to broader rules</td>
			</tr>
			<tr>
					<td>Drop</td>
					<td><code>CNAME rpz-drop.</code></td>
					<td>Silent discard; the client times out</td>
			</tr>
			<tr>
					<td>TCP-only</td>
					<td><code>CNAME rpz-tcp-only.</code></td>
					<td>Force the client to retry over TCP</td>
			</tr>
	</tbody>
</table>
<h3 id="nxdomain-block-domain">NXDOMAIN (Block Domain) <a class="anchor" data-pagefind-ignore href="#nxdomain-block-domain" aria-label="Link to this section">#</a></h3>
<p>Return &ldquo;domain not found&rdquo;. Add the <code>*.</code> wildcard as well, or subdomains still resolve:</p>
<pre tabindex="0"><code>; CNAME to root (.) returns NXDOMAIN
badsite.com         CNAME   .
*.badsite.com       CNAME   .
</code></pre><h3 id="nodata-block-record-type">NODATA (Block Record Type) <a class="anchor" data-pagefind-ignore href="#nodata-block-record-type" aria-label="Link to this section">#</a></h3>
<p>Return &ldquo;no records of requested type&rdquo;:</p>
<pre tabindex="0"><code>; CNAME to wildcard (*.) returns NODATA
tracking.example.com    CNAME   *.
</code></pre><h3 id="custom-response">Custom Response <a class="anchor" data-pagefind-ignore href="#custom-response" aria-label="Link to this section">#</a></h3>
<p>Return specific IP addresses, for example a block page that explains what happened:</p>
<pre tabindex="0"><code>; Redirect to block page
blocked-site.com    A       192.168.1.100
blocked-site.com    AAAA    fd00::100

; Redirect to walled garden
malware.com         CNAME   walled-garden.example.com.
</code></pre><h3 id="passthru-allow">Passthru (Allow) <a class="anchor" data-pagefind-ignore href="#passthru-allow" aria-label="Link to this section">#</a></h3>
<p>Override blocking for specific names. The more specific rule wins over the wildcard:</p>
<pre tabindex="0"><code>; Block entire domain
badsite.com             CNAME   .
*.badsite.com           CNAME   .

; But allow specific subdomain
api.badsite.com         CNAME   rpz-passthru.
</code></pre><h3 id="drop-silent-discard">Drop (Silent Discard) <a class="anchor" data-pagefind-ignore href="#drop-silent-discard" aria-label="Link to this section">#</a></h3>
<p>Silently drop queries (no response sent). The client waits for its timeout, so use this sparingly:</p>
<pre tabindex="0"><code>drop-this.com       CNAME   rpz-drop.
</code></pre><h3 id="tcp-only">TCP-Only <a class="anchor" data-pagefind-ignore href="#tcp-only" aria-label="Link to this section">#</a></h3>
<p>Force TCP retry (rarely used):</p>
<pre tabindex="0"><code>force-tcp.com       CNAME   rpz-tcp-only.
</code></pre><h2 id="trigger-types">Trigger Types <a class="anchor" data-pagefind-ignore href="#trigger-types" aria-label="Link to this section">#</a></h2>
<p>The owner name decides what a rule matches. A suffix marks the trigger type:</p>
<table>
	<thead>
			<tr>
					<th>Trigger</th>
					<th>Owner name</th>
					<th>Matches</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>QNAME</td>
					<td><code>domain</code></td>
					<td>The name the client asked for</td>
			</tr>
			<tr>
					<td>IP</td>
					<td><code>….rpz-ip</code></td>
					<td>Addresses in the answer</td>
			</tr>
			<tr>
					<td>NSIP</td>
					<td><code>….rpz-nsip</code></td>
					<td>IP addresses of the domain&rsquo;s name servers</td>
			</tr>
			<tr>
					<td>NSDNAME</td>
					<td><code>….rpz-nsdname</code></td>
					<td>Names of the domain&rsquo;s name servers</td>
			</tr>
			<tr>
					<td>Client IP</td>
					<td><code>….rpz-client-ip</code></td>
					<td>The address of the client asking</td>
			</tr>
	</tbody>
</table>
<h3 id="qname-triggers">QNAME Triggers <a class="anchor" data-pagefind-ignore href="#qname-triggers" aria-label="Link to this section">#</a></h3>
<p>Match the queried domain name. This is the most common trigger, and what blocklists use:</p>
<pre tabindex="0"><code>; Exact match
badsite.com         CNAME   .

; Wildcard match (all subdomains)
*.badsite.com       CNAME   .
</code></pre><h3 id="ip-triggers">IP Triggers <a class="anchor" data-pagefind-ignore href="#ip-triggers" aria-label="Link to this section">#</a></h3>
<p>Match response IP addresses, to catch any domain that points into a bad network. The owner name is the prefix length followed by the address octets in reverse order:</p>
<pre tabindex="0"><code>; Block any response containing 10.20.30.40
32.40.30.20.10.rpz-ip    CNAME   .

; Block responses in 192.168.1.0/24
24.0.1.168.192.rpz-ip    CNAME   .
</code></pre><h3 id="nsip-triggers">NSIP Triggers <a class="anchor" data-pagefind-ignore href="#nsip-triggers" aria-label="Link to this section">#</a></h3>
<p>Match nameserver IP addresses. Useful when many bad domains share the same name servers:</p>
<pre tabindex="0"><code>; Block domains hosted on nameserver IP 10.20.30.40
32.40.30.20.10.rpz-nsip  CNAME   .
</code></pre><h3 id="nsdname-triggers">NSDNAME Triggers <a class="anchor" data-pagefind-ignore href="#nsdname-triggers" aria-label="Link to this section">#</a></h3>
<p>Match nameserver domain names:</p>
<pre tabindex="0"><code>; Block domains using this nameserver
ns.malicious-hosting.com.rpz-nsdname    CNAME   .
</code></pre><h3 id="client-ip-triggers">Client IP Triggers <a class="anchor" data-pagefind-ignore href="#client-ip-triggers" aria-label="Link to this section">#</a></h3>
<p>Match client IP addresses, to give one client a different policy:</p>
<pre tabindex="0"><code>; Different policy for client 192.168.1.50
32.50.1.168.192.rpz-client-ip  CNAME   rpz-passthru.
</code></pre><h2 id="multiple-rpz-zones">Multiple RPZ Zones <a class="anchor" data-pagefind-ignore href="#multiple-rpz-zones" aria-label="Link to this section">#</a></h2>
<p>Split rules by source: your own overrides, and one zone per feed. Each can be managed and updated separately.</p>
<pre tabindex="0"><code>options {
    response-policy {
        zone &#34;rpz-local&#34; policy given;      # Local overrides
        zone &#34;rpz-malware&#34; policy given;    # Malware blocklist
        zone &#34;rpz-phishing&#34; policy given;   # Phishing blocklist
        zone &#34;rpz-ads&#34; policy given;        # Ad blocking
    };
};

zone &#34;rpz-local&#34; {
    type primary;
    file &#34;/var/named/rpz/local.zone&#34;;
};

zone &#34;rpz-malware&#34; {
    type secondary;
    file &#34;/var/named/rpz/malware.zone&#34;;
    primaries { 192.168.1.10; };
};

zone &#34;rpz-phishing&#34; {
    type secondary;
    file &#34;/var/named/rpz/phishing.zone&#34;;
    primaries { 192.168.1.10; };
};

zone &#34;rpz-ads&#34; {
    type secondary;
    file &#34;/var/named/rpz/ads.zone&#34;;
    primaries { 192.168.1.10; };
};
</code></pre><ul>
<li><code>policy given</code>: use the action from the zone&rsquo;s records (the default).</li>
<li>The feed zones are slave zones, transferred from the master at 192.168.1.10. One server maintains the lists for many resolvers.</li>
</ul>
<p>Zones are evaluated in order - first match wins. Put your own overrides first.</p>
<h2 id="using-external-blocklists">Using External Blocklists <a class="anchor" data-pagefind-ignore href="#using-external-blocklists" aria-label="Link to this section">#</a></h2>
<h3 id="converting-blocklists-to-rpz-format">Converting Blocklists to RPZ Format <a class="anchor" data-pagefind-ignore href="#converting-blocklists-to-rpz-format" aria-label="Link to this section">#</a></h3>
<p>Many blocklists are available in hosts file format. This script writes a SOA, NS and one <code>CNAME .</code> (NXDOMAIN) rule per domain. The serial is based on the current hour, so every run produces a higher serial.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># convert-blocklist.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">INPUT</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$1</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">OUTPUT</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$2</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">SOA_SERIAL</span><span class="o">=</span><span class="k">$(</span>date +%Y%m%d%H<span class="k">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">cat &gt; <span class="s2">&#34;</span><span class="nv">$OUTPUT</span><span class="s2">&#34;</span> <span class="s">&lt;&lt; EOF
</span></span></span><span class="line"><span class="cl"><span class="s">\$TTL 300
</span></span></span><span class="line"><span class="cl"><span class="s">@   IN  SOA localhost. admin.localhost. (
</span></span></span><span class="line"><span class="cl"><span class="s">        $SOA_SERIAL  ; Serial
</span></span></span><span class="line"><span class="cl"><span class="s">        3600         ; Refresh
</span></span></span><span class="line"><span class="cl"><span class="s">        1800         ; Retry
</span></span></span><span class="line"><span class="cl"><span class="s">        604800       ; Expire
</span></span></span><span class="line"><span class="cl"><span class="s">        300 )        ; Minimum TTL
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">    IN  NS  localhost.
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">; Converted from $INPUT
</span></span></span><span class="line"><span class="cl"><span class="s">EOF</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Convert hosts file format (0.0.0.0 domain or 127.0.0.1 domain)</span>
</span></span><span class="line"><span class="cl">grep -E <span class="s2">&#34;^(0\.0\.0\.0|127\.0\.0\.1)&#34;</span> <span class="s2">&#34;</span><span class="nv">$INPUT</span><span class="s2">&#34;</span> <span class="p">|</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    awk <span class="s1">&#39;{print $2}&#39;</span> <span class="p">|</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    grep -v localhost <span class="p">|</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    grep -v <span class="s1">&#39;^0\.0\.0\.0$&#39;</span> <span class="p">|</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    sort -u <span class="p">|</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="k">while</span> <span class="nb">read</span> domain<span class="p">;</span> <span class="k">do</span>
</span></span><span class="line"><span class="cl">        <span class="nb">echo</span> <span class="s2">&#34;</span><span class="nv">$domain</span><span class="s2"> CNAME .&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="k">done</span> &gt;&gt; <span class="s2">&#34;</span><span class="nv">$OUTPUT</span><span class="s2">&#34;</span>
</span></span></code></pre></div><p>Usage:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">./convert-blocklist.sh hosts.txt /var/named/rpz/blocklist.zone
</span></span><span class="line"><span class="cl">rndc reload rpz-blocklist
</span></span></code></pre></div><p>This assumes a zone <code>rpz-blocklist</code> with file <code>/var/named/rpz/blocklist.zone</code> is defined and listed in <code>response-policy</code>, like the zones in the complete example below. BIND applies RPZ changes at most once per <code>min-update-interval</code> (60 seconds by default), so new rules can take up to a minute to take effect.</p>
<h3 id="popular-blocklist-sources">Popular Blocklist Sources <a class="anchor" data-pagefind-ignore href="#popular-blocklist-sources" aria-label="Link to this section">#</a></h3>
<table>
	<thead>
			<tr>
					<th>Source</th>
					<th>Covers</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Steven Black&rsquo;s hosts</td>
					<td>Unified hosts with multiple extensions</td>
			</tr>
			<tr>
					<td>OISD</td>
					<td>Comprehensive ad/tracking blocklist</td>
			</tr>
			<tr>
					<td>URLhaus</td>
					<td>Malware URL blocklist</td>
			</tr>
			<tr>
					<td>PhishTank</td>
					<td>Phishing URL database</td>
			</tr>
			<tr>
					<td>Spamhaus</td>
					<td>Malware and botnet domains</td>
			</tr>
	</tbody>
</table>
<h3 id="automated-updates">Automated Updates <a class="anchor" data-pagefind-ignore href="#automated-updates" aria-label="Link to this section">#</a></h3>
<p>Blocklists change daily. This script downloads the list, converts it, fixes permissions and reloads the zone. <code>curl -f</code> aborts on HTTP errors, so a failed download does not replace the zone with an empty one.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># /usr/local/bin/update-rpz.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">RPZ_DIR</span><span class="o">=</span><span class="s2">&#34;/var/named/rpz&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">BLOCKLIST_URL</span><span class="o">=</span><span class="s2">&#34;https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Download blocklist (abort on HTTP errors, or a failed download empties the zone)</span>
</span></span><span class="line"><span class="cl">curl -fsS <span class="s2">&#34;</span><span class="nv">$BLOCKLIST_URL</span><span class="s2">&#34;</span> -o /tmp/blocklist.txt <span class="o">||</span> <span class="nb">exit</span> <span class="m">1</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Convert to RPZ format</span>
</span></span><span class="line"><span class="cl">/usr/local/bin/convert-blocklist.sh /tmp/blocklist.txt <span class="s2">&#34;</span><span class="nv">$RPZ_DIR</span><span class="s2">/blocklist.zone&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Fix permissions</span>
</span></span><span class="line"><span class="cl">chown named:named <span class="s2">&#34;</span><span class="nv">$RPZ_DIR</span><span class="s2">/blocklist.zone&#34;</span>
</span></span><span class="line"><span class="cl">chmod <span class="m">640</span> <span class="s2">&#34;</span><span class="nv">$RPZ_DIR</span><span class="s2">/blocklist.zone&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Reload zone</span>
</span></span><span class="line"><span class="cl">rndc reload rpz-blocklist
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Cleanup</span>
</span></span><span class="line"><span class="cl">rm /tmp/blocklist.txt
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;RPZ blocklist updated: </span><span class="k">$(</span>date<span class="k">)</span><span class="s2">&#34;</span>
</span></span></code></pre></div><p>Schedule with cron:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Update blocklist daily at 3 AM</span>
</span></span><span class="line"><span class="cl"><span class="m">0</span> <span class="m">3</span> * * * /usr/local/bin/update-rpz.sh &gt;&gt; /var/log/rpz-update.log 2&gt;<span class="p">&amp;</span><span class="m">1</span>
</span></span></code></pre></div><h2 id="creating-a-block-page">Creating a Block Page <a class="anchor" data-pagefind-ignore href="#creating-a-block-page" aria-label="Link to this section">#</a></h2>
<p>Optional. With NXDOMAIN users just see &ldquo;site not found&rdquo;; a block page tells them the site was blocked on purpose and who to contact. It only works for plain HTTP; HTTPS sites show a certificate error instead.</p>
<h3 id="nginx-configuration">Nginx Configuration <a class="anchor" data-pagefind-ignore href="#nginx-configuration" aria-label="Link to this section">#</a></h3>
<p>Serve the same page for every path, whatever URL the user tried:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-nginx" data-lang="nginx"><span class="line"><span class="cl"><span class="k">server</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="kn">listen</span> <span class="mi">80</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="kn">server_name</span> <span class="s">blocked.example.com</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="kn">root</span> <span class="s">/var/www/blocked</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="kn">location</span> <span class="s">/</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="kn">try_files</span> <span class="nv">$uri</span> <span class="s">/index.html</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span></code></pre></div><h3 id="block-page-html">Block Page HTML <a class="anchor" data-pagefind-ignore href="#block-page-html" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-html" data-lang="html"><span class="line"><span class="cl"><span class="cp">&lt;!DOCTYPE html&gt;</span>
</span></span><span class="line"><span class="cl"><span class="p">&lt;</span><span class="nt">html</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl"><span class="p">&lt;</span><span class="nt">head</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">    <span class="p">&lt;</span><span class="nt">title</span><span class="p">&gt;</span>Access Blocked<span class="p">&lt;/</span><span class="nt">title</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">    <span class="p">&lt;</span><span class="nt">style</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">        <span class="nt">body</span> <span class="p">{</span> <span class="k">font-family</span><span class="p">:</span> <span class="kc">sans-serif</span><span class="p">;</span> <span class="k">text-align</span><span class="p">:</span> <span class="kc">center</span><span class="p">;</span> <span class="k">padding</span><span class="p">:</span> <span class="mi">50</span><span class="kt">px</span><span class="p">;</span> <span class="p">}</span>
</span></span><span class="line"><span class="cl">        <span class="nt">h1</span> <span class="p">{</span> <span class="k">color</span><span class="p">:</span> <span class="mh">#d32f2f</span><span class="p">;</span> <span class="p">}</span>
</span></span><span class="line"><span class="cl">        <span class="p">.</span><span class="nc">info</span> <span class="p">{</span> <span class="k">color</span><span class="p">:</span> <span class="mh">#666</span><span class="p">;</span> <span class="k">margin-top</span><span class="p">:</span> <span class="mi">20</span><span class="kt">px</span><span class="p">;</span> <span class="p">}</span>
</span></span><span class="line"><span class="cl">    <span class="p">&lt;/</span><span class="nt">style</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl"><span class="p">&lt;/</span><span class="nt">head</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl"><span class="p">&lt;</span><span class="nt">body</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">    <span class="p">&lt;</span><span class="nt">h1</span><span class="p">&gt;</span>Access Blocked<span class="p">&lt;/</span><span class="nt">h1</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">    <span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span>This site has been blocked by your network administrator.<span class="p">&lt;/</span><span class="nt">p</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">    <span class="p">&lt;</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">&#34;info&#34;</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">        <span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span>If you believe this is an error, please contact IT support.<span class="p">&lt;/</span><span class="nt">p</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">        <span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span>Blocked domain: <span class="p">&lt;</span><span class="nt">script</span><span class="p">&gt;</span><span class="nb">document</span><span class="p">.</span><span class="nx">write</span><span class="p">(</span><span class="nx">location</span><span class="p">.</span><span class="nx">hostname</span><span class="p">);&lt;/</span><span class="nt">script</span><span class="p">&gt;&lt;/</span><span class="nt">p</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">    <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl"><span class="p">&lt;/</span><span class="nt">body</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl"><span class="p">&lt;/</span><span class="nt">html</span><span class="p">&gt;</span>
</span></span></code></pre></div><h3 id="rpz-configuration-for-block-page">RPZ Configuration for Block Page <a class="anchor" data-pagefind-ignore href="#rpz-configuration-for-block-page" aria-label="Link to this section">#</a></h3>
<p>Point blocked domains at the web server, by address or by name:</p>
<pre tabindex="0"><code>; Redirect blocked domains to block page
bad-domain.com          A       192.168.1.100
*.bad-domain.com        A       192.168.1.100

; Or use CNAME
bad-domain.com          CNAME   blocked.example.com.
</code></pre><h2 id="logging-rpz-actions">Logging RPZ Actions <a class="anchor" data-pagefind-ignore href="#logging-rpz-actions" aria-label="Link to this section">#</a></h2>
<p>Send the <code>rpz</code> category to its own file. Every rewrite is logged with the client, the name and the matching zone.</p>
<pre tabindex="0"><code>logging {
    channel rpz_log {
        file &#34;/var/log/named/rpz.log&#34; versions 10 size 50m;
        severity info;
        print-time yes;
        print-category yes;
        print-severity yes;
    };
    
    category rpz { rpz_log; };
};
</code></pre><p>Log format shows:</p>
<ul>
<li>Query that triggered RPZ</li>
<li>Which RPZ zone matched</li>
<li>What action was taken</li>
<li>Client IP address</li>
</ul>
<h3 id="analyzing-rpz-logs">Analyzing RPZ Logs <a class="anchor" data-pagefind-ignore href="#analyzing-rpz-logs" aria-label="Link to this section">#</a></h3>
<p>Two quick reports from today&rsquo;s log: the most blocked domains, and the clients that trigger the most blocks (often an infected machine).</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Top blocked domains today</span>
</span></span><span class="line"><span class="cl">grep <span class="s2">&#34;</span><span class="k">$(</span>date +%d-%b-%Y<span class="k">)</span><span class="s2">&#34;</span> /var/log/named/rpz.log <span class="p">|</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    grep -oP <span class="s2">&#34;rpz QNAME \S+ rewrite \K[^/]+&#34;</span> <span class="p">|</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    sort <span class="p">|</span> uniq -c <span class="p">|</span> sort -rn <span class="p">|</span> head -20
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Clients triggering most blocks</span>
</span></span><span class="line"><span class="cl">grep <span class="s2">&#34;</span><span class="k">$(</span>date +%d-%b-%Y<span class="k">)</span><span class="s2">&#34;</span> /var/log/named/rpz.log <span class="p">|</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    grep -oP <span class="s2">&#34;client @0x[0-9a-f]+ \K[0-9.]+&#34;</span> <span class="p">|</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    sort <span class="p">|</span> uniq -c <span class="p">|</span> sort -rn <span class="p">|</span> head -10
</span></span></code></pre></div><h2 id="whitelisting">Whitelisting <a class="anchor" data-pagefind-ignore href="#whitelisting" aria-label="Link to this section">#</a></h2>
<p>Blocklists contain false positives. A whitelist zone with passthru rules lets you fix those locally without editing the feed.</p>
<pre tabindex="0"><code>; /var/named/rpz/whitelist.zone
$TTL 300
@   IN  SOA localhost. admin.localhost. (
        2024010101  ; Serial
        3600        ; Refresh
        1800        ; Retry
        604800      ; Expire
        300 )       ; Minimum TTL

    IN  NS  localhost.

; Whitelist entries (passthru overrides blocking)
legitimate-site.com         CNAME   rpz-passthru.
*.legitimate-site.com       CNAME   rpz-passthru.

required-service.example.com CNAME  rpz-passthru.
</code></pre><p>Place whitelist zone first, because the first matching zone wins:</p>
<pre tabindex="0"><code>response-policy {
    zone &#34;rpz-whitelist&#34;;     # Check whitelist first
    zone &#34;rpz-malware&#34;;
    zone &#34;rpz-ads&#34;;
};
</code></pre><h2 id="performance-considerations">Performance Considerations <a class="anchor" data-pagefind-ignore href="#performance-considerations" aria-label="Link to this section">#</a></h2>
<h3 id="update-interval-and-ttl">Update Interval and TTL <a class="anchor" data-pagefind-ignore href="#update-interval-and-ttl" aria-label="Link to this section">#</a></h3>
<p>Large blocklists cost memory and reload time. Two settings per zone control how often changes are applied and how long rewritten answers are cached:</p>
<pre tabindex="0"><code>options {
    response-policy {
        zone &#34;rpz-blocklist&#34; 
            max-policy-ttl 300
            min-update-interval 60;
    };
};
</code></pre><ul>
<li><code>max-policy-ttl 300</code>: rewritten answers have a TTL of at most 5 minutes, so an unblocked domain works again quickly.</li>
<li><code>min-update-interval 60</code>: apply zone updates at most once a minute; raise it for very large zones that update often.</li>
</ul>
<h3 id="nsipnsdname-performance">NSIP/NSDNAME Performance <a class="anchor" data-pagefind-ignore href="#nsipnsdname-performance" aria-label="Link to this section">#</a></h3>
<p>NSIP and NSDNAME triggers require additional lookups of the name servers. Turn them off for zones that only contain QNAME rules:</p>
<pre tabindex="0"><code>// Disable expensive triggers if not needed
options {
    response-policy {
        zone &#34;rpz-blocklist&#34; nsip-enable no nsdname-enable no;
    };
};
</code></pre><h3 id="recursive-queries">Recursive Queries <a class="anchor" data-pagefind-ignore href="#recursive-queries" aria-label="Link to this section">#</a></h3>
<p>RPZ only affects recursive queries. For authoritative-only servers, RPZ has no effect.</p>
<h2 id="complete-configuration-example">Complete Configuration Example <a class="anchor" data-pagefind-ignore href="#complete-configuration-example" aria-label="Link to this section">#</a></h2>
<p>A validating resolver with a whitelist and three blocklist zones:</p>
<pre tabindex="0"><code>// /etc/named.conf

acl &#34;trusted&#34; {
    localhost;
    localnets;
    192.168.0.0/16;
};

options {
    directory &#34;/var/named&#34;;
    
    recursion yes;
    allow-recursion { trusted; };
    
    dnssec-validation auto;
    
    response-policy {
        zone &#34;rpz-whitelist&#34; policy passthru;
        zone &#34;rpz-malware&#34; policy given;
        zone &#34;rpz-phishing&#34; policy given;
        zone &#34;rpz-ads&#34; policy given;
    } qname-wait-recurse no;
};

logging {
    channel rpz_log {
        file &#34;/var/log/named/rpz.log&#34; versions 10 size 50m;
        severity info;
        print-time yes;
        print-category yes;
    };
    
    category rpz { rpz_log; };
};

zone &#34;rpz-whitelist&#34; {
    type primary;
    file &#34;/var/named/rpz/whitelist.zone&#34;;
    allow-query { none; };
};

zone &#34;rpz-malware&#34; {
    type primary;
    file &#34;/var/named/rpz/malware.zone&#34;;
    allow-query { none; };
};

zone &#34;rpz-phishing&#34; {
    type primary;
    file &#34;/var/named/rpz/phishing.zone&#34;;
    allow-query { none; };
};

zone &#34;rpz-ads&#34; {
    type primary;
    file &#34;/var/named/rpz/ads.zone&#34;;
    allow-query { none; };
};

zone &#34;.&#34; {
    type hint;
    file &#34;named.ca&#34;;
};
</code></pre><ul>
<li><code>policy passthru</code> on <code>rpz-whitelist</code>: every name in that zone resolves normally, whatever its record says.</li>
<li><code>policy given</code> on the blocklists: use the action from each record.</li>
</ul>
<h2 id="testing-rpz">Testing RPZ <a class="anchor" data-pagefind-ignore href="#testing-rpz" aria-label="Link to this section">#</a></h2>
<h3 id="verify-blocking">Verify Blocking <a class="anchor" data-pagefind-ignore href="#verify-blocking" aria-label="Link to this section">#</a></h3>
<p>Query a domain from your blocklist and check the log:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Query blocked domain</span>
</span></span><span class="line"><span class="cl">dig @localhost blocked-domain.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Should return NXDOMAIN or your block page IP</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check RPZ logs</span>
</span></span><span class="line"><span class="cl">tail -f /var/log/named/rpz.log
</span></span></code></pre></div><h3 id="test-passthru">Test Passthru <a class="anchor" data-pagefind-ignore href="#test-passthru" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Verify whitelisted domain resolves normally</span>
</span></span><span class="line"><span class="cl">dig @localhost whitelisted-domain.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Should return actual IP, not blocked</span>
</span></span></code></pre></div><h3 id="debug-mode">Debug Mode <a class="anchor" data-pagefind-ignore href="#debug-mode" aria-label="Link to this section">#</a></h3>
<p>If a rule does not fire, turn on query logging temporarily to see what clients actually ask:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">rndc querylog on
</span></span><span class="line"><span class="cl"><span class="c1"># Run tests</span>
</span></span><span class="line"><span class="cl">rndc querylog off
</span></span></code></pre></div><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Likely cause</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Blocked domain still resolves</td>
					<td>Zone not listed in <code>response-policy</code>, missing <code>*.</code> rule for subdomains, or update not yet applied (<code>min-update-interval</code>)</td>
			</tr>
			<tr>
					<td>SERVFAIL instead of block answer</td>
					<td><code>qname-wait-recurse</code> left at <code>yes</code> and the domain&rsquo;s name servers are broken</td>
			</tr>
			<tr>
					<td>Whitelisted domain still blocked</td>
					<td>Whitelist zone is not listed first</td>
			</tr>
			<tr>
					<td>No effect at all</td>
					<td>Client uses another resolver, or the server is authoritative-only</td>
			</tr>
	</tbody>
</table>
<h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub: <a href="https://github.com/pderuiter/blog-bind-rpz" rel="noopener">pderuiter/blog-bind-rpz</a>. It creates an Ubuntu 24.04 VM on Proxmox and builds the resolver from this post with the whitelist, local and blocklist RPZ zones, the conversion and daily update scripts and RPZ logging (the block page is optional); run <code>terraform apply</code>, then <code>ansible-playbook site.yml</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>Response Policy Zones provide DNS-level security without client software or network proxies. Combine regularly updated blocklists, a local whitelist and logging for an effective first line of defense against malware, phishing and unwanted content.</p>
<p>The next post will cover DNS over TLS (DoT), adding transport encryption to your DNS infrastructure for privacy and security.</p>
]]></content:encoded></item><item><title>Securing DNS Traffic with DNS over TLS (DoT) on BIND</title><link>https://blog.bsdserver.nl/securing-dns-traffic-with-dns-over-tls-dot-on-bind/</link><guid isPermaLink="false">693b6eb479eb54000160a5a5</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:24:04 +0000</pubDate><description>Traditional DNS queries travel in plaintext, exposing your browsing habits to network observers.</description><category>BIND</category><category>DNS</category><category>DNS over TLS</category><category>TLS</category><category>Security</category><category>Encryption</category><category>Homelab</category><category>Linux</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/securing-dns-with-DoT.png" medium="image"/><content:encoded><![CDATA[<p>Traditional DNS queries travel in plaintext, exposing your browsing habits to network observers. Anyone on the path can read them, and can change the answers.</p>
<p>DNS over TLS (DoT) encrypts DNS traffic between clients and resolvers, providing privacy and preventing tampering. This post covers implementing DoT on BIND 9 in two roles: as a DoT server for your clients, and as a forwarder that sends its own queries upstream over DoT.</p>
<h2 id="why-dot">Why DoT? <a class="anchor" data-pagefind-ignore href="#why-dot" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Privacy</strong>: ISPs and network observers cannot see DNS queries</li>
<li><strong>Integrity</strong>: Prevents DNS query/response manipulation</li>
<li><strong>Authentication</strong>: Server identity verified via TLS certificates</li>
<li><strong>Compliance</strong>: Helps meet data protection requirements</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> when DNS crosses networks you do not trust: Wi-Fi, branch links, the path to a public resolver, or mobile clients using your resolver.</li>
<li><strong>Skip it</strong> on a trusted LAN segment between a client and a resolver next to it. It adds certificates to manage and TCP connections to carry, for little gain.</li>
</ul>
<h3 id="dot-vs-doh">DoT vs DoH <a class="anchor" data-pagefind-ignore href="#dot-vs-doh" aria-label="Link to this section">#</a></h3>
<p>Both encrypt DNS with TLS. The difference is the port, and with it who can see and block the traffic.</p>
<table>
	<thead>
			<tr>
					<th>Feature</th>
					<th>DNS over TLS (DoT)</th>
					<th>DNS over HTTPS (DoH)</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Port</td>
					<td>853 (dedicated)</td>
					<td>443 (shared with HTTPS)</td>
			</tr>
			<tr>
					<td>Protocol</td>
					<td>TLS directly</td>
					<td>HTTP/2 over TLS</td>
			</tr>
			<tr>
					<td>Blockable</td>
					<td>Easily (port 853)</td>
					<td>Harder to distinguish</td>
			</tr>
			<tr>
					<td>Performance</td>
					<td>Better (simpler)</td>
					<td>Slightly more overhead</td>
			</tr>
			<tr>
					<td>Use case</td>
					<td>Network operators</td>
					<td>End users/browsers</td>
			</tr>
	</tbody>
</table>
<h2 id="how-it-works">How it works <a class="anchor" data-pagefind-ignore href="#how-it-works" aria-label="Link to this section">#</a></h2>
<p>DoT wraps standard DNS queries in TLS encryption:</p>
<ol>
<li>Client initiates TLS connection to port 853</li>
<li>TLS handshake establishes encrypted channel</li>
<li>DNS queries and responses flow encrypted</li>
<li>Connection may persist for multiple queries</li>
</ol>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>DoT client</td>
					<td>Laptop, phone, or a local stub (systemd-resolved, Stubby)</td>
					<td>Opens TLS to port 853, checks the server certificate, sends queries.</td>
			</tr>
			<tr>
					<td>BIND DoT listener</td>
					<td>Your resolver</td>
					<td>Terminates TLS with the <code>tls</code> block&rsquo;s certificate and answers as usual.</td>
			</tr>
			<tr>
					<td>BIND DoT forwarder (optional)</td>
					<td>Your resolver</td>
					<td>Sends its own queries to an upstream DoT resolver and checks that server&rsquo;s certificate.</td>
			</tr>
			<tr>
					<td>Upstream resolver</td>
					<td>Cloudflare, Google, Quad9</td>
					<td>Resolves the queries you forward.</td>
			</tr>
	</tbody>
</table>
<p>The flow: client → TLS on 853 → BIND → cache, or recursion / DoT forwarder → answer back over the same TLS connection.</p>
<h2 id="prerequisites">Prerequisites <a class="anchor" data-pagefind-ignore href="#prerequisites" aria-label="Link to this section">#</a></h2>
<p>Before configuring DoT, ensure you have:</p>
<ol>
<li>BIND 9.18+ (native DoT listener; forwarding over DoT needs BIND 9.20+) or BIND with stunnel/nginx</li>
<li>Valid TLS certificate (Let&rsquo;s Encrypt works well)</li>
<li>Port 853 accessible through firewall</li>
<li>A working recursive resolver setup</li>
</ol>
<h2 id="native-dot-in-bind-918">Native DoT in BIND 9.18+ <a class="anchor" data-pagefind-ignore href="#native-dot-in-bind-918" aria-label="Link to this section">#</a></h2>
<p>BIND 9.18 and later include native DNS over TLS support (it was developed in the 9.17 development branch). No proxy is needed: a named <code>tls</code> block holds the certificate, and <code>listen-on port 853 tls &lt;name&gt;</code> opens the listener.</p>
<h3 id="basic-dot-listener-configuration">Basic DoT Listener Configuration <a class="anchor" data-pagefind-ignore href="#basic-dot-listener-configuration" aria-label="Link to this section">#</a></h3>
<p>This keeps the plain listener on port 53 and adds a TLS listener on 853 next to it.</p>
<ul>
<li><code>listen-on port 853 tls local-tls</code>: the DoT listener, using the <code>tls local-tls</code> block below.</li>
<li><code>tcp-clients</code>: maximum concurrent TCP connections, DoT included. Raise it, because every DoT client holds a connection open.</li>
<li><code>tcp-keepalive-timeout</code>: how long an idle connection stays open for clients that use EDNS keepalive. In units of 100 ms.</li>
<li><code>dhparam-file</code>: optional, only used by DHE cipher suites.</li>
<li><code>protocols</code> and <code>ciphers</code>: TLS 1.2 and 1.3 only, with ECDHE suites for forward secrecy.</li>
<li><code>prefer-server-ciphers</code>: the server&rsquo;s cipher order wins over the client&rsquo;s.</li>
<li><code>session-tickets</code>: lets clients resume a TLS session without a full handshake.</li>
</ul>
<pre tabindex="0"><code class="language-named" data-lang="named">// /etc/bind/named.conf.options

options {
    directory &#34;/var/cache/bind&#34;;
    
    // Standard DNS listener
    listen-on { 127.0.0.1; 192.168.1.1; };
    listen-on-v6 { ::1; };
    
    // DNS over TLS listener
    listen-on port 853 tls local-tls { 127.0.0.1; 192.168.1.1; };
    listen-on-v6 port 853 tls local-tls { ::1; };
    
    // Resolver settings
    recursion yes;
    allow-recursion { localhost; 192.168.0.0/16; };
    
    dnssec-validation auto;
    
    // Performance tuning for DoT
    tcp-clients 1000;
    tcp-keepalive-timeout 300;    // units of 100 ms: 300 = 30 seconds
};

// TLS configuration
tls local-tls {
    cert-file &#34;/etc/bind/tls/cert.pem&#34;;
    key-file &#34;/etc/bind/tls/key.pem&#34;;
    
    // Optional: Diffie-Hellman parameters for forward secrecy
    dhparam-file &#34;/etc/bind/tls/dhparam.pem&#34;;
    
    // TLS protocol settings
    protocols { TLSv1.2; TLSv1.3; };
    
    // Strong cipher suites
    ciphers &#34;ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305&#34;;
    
    // Prefer server cipher order
    prefer-server-ciphers yes;
    
    // Session resumption
    session-tickets yes;
};
</code></pre><p>Check the file with <code>named-checkconf</code> before reloading.</p>
<h3 id="generating-tls-certificates">Generating TLS Certificates <a class="anchor" data-pagefind-ignore href="#generating-tls-certificates" aria-label="Link to this section">#</a></h3>
<p>BIND needs a certificate whose name matches the hostname your clients use (<code>dns.example.com</code> here).</p>
<table>
	<thead>
			<tr>
					<th>Option</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Let&rsquo;s Encrypt</td>
					<td>Anything clients outside your lab use. Clients that verify the certificate trust it out of the box.</td>
			</tr>
			<tr>
					<td>Self-signed</td>
					<td>Testing only. Clients must skip verification or trust your certificate by hand.</td>
			</tr>
	</tbody>
</table>
<h4 id="using-lets-encrypt">Using Let&rsquo;s Encrypt <a class="anchor" data-pagefind-ignore href="#using-lets-encrypt" aria-label="Link to this section">#</a></h4>
<p>The standalone method briefly runs its own web server on port 80, so that port must be free and reachable. BIND runs as user <code>bind</code> and cannot read the files under <code>/etc/letsencrypt</code>, so copy them to <code>/etc/bind/tls</code> with the right owner.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Install certbot</span>
</span></span><span class="line"><span class="cl">apt install certbot
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Obtain certificate (standalone method)</span>
</span></span><span class="line"><span class="cl">certbot certonly --standalone -d dns.example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create directory for BIND</span>
</span></span><span class="line"><span class="cl">mkdir -p /etc/bind/tls
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Copy certificates with correct permissions</span>
</span></span><span class="line"><span class="cl">cp /etc/letsencrypt/live/dns.example.com/fullchain.pem /etc/bind/tls/cert.pem
</span></span><span class="line"><span class="cl">cp /etc/letsencrypt/live/dns.example.com/privkey.pem /etc/bind/tls/key.pem
</span></span><span class="line"><span class="cl">chown bind:bind /etc/bind/tls/*.pem
</span></span><span class="line"><span class="cl">chmod <span class="m">640</span> /etc/bind/tls/*.pem
</span></span></code></pre></div><h4 id="auto-renewal-hook">Auto-renewal Hook <a class="anchor" data-pagefind-ignore href="#auto-renewal-hook" aria-label="Link to this section">#</a></h4>
<p>Let&rsquo;s Encrypt certificates last 90 days. certbot runs scripts in <code>renewal-hooks/deploy/</code> after each successful renewal; this one copies the new files and reloads BIND.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># /etc/letsencrypt/renewal-hooks/deploy/bind-tls.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">DOMAIN</span><span class="o">=</span><span class="s2">&#34;dns.example.com&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">BIND_TLS_DIR</span><span class="o">=</span><span class="s2">&#34;/etc/bind/tls&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Copy new certificates</span>
</span></span><span class="line"><span class="cl">cp /etc/letsencrypt/live/<span class="nv">$DOMAIN</span>/fullchain.pem <span class="nv">$BIND_TLS_DIR</span>/cert.pem
</span></span><span class="line"><span class="cl">cp /etc/letsencrypt/live/<span class="nv">$DOMAIN</span>/privkey.pem <span class="nv">$BIND_TLS_DIR</span>/key.pem
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Set permissions</span>
</span></span><span class="line"><span class="cl">chown bind:bind <span class="nv">$BIND_TLS_DIR</span>/*.pem
</span></span><span class="line"><span class="cl">chmod <span class="m">640</span> <span class="nv">$BIND_TLS_DIR</span>/*.pem
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Reload BIND</span>
</span></span><span class="line"><span class="cl">rndc reload
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;BIND TLS certificates updated&#34;</span>
</span></span></code></pre></div><p>Make the hook executable, certbot skips hooks that are not:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">chmod +x /etc/letsencrypt/renewal-hooks/deploy/bind-tls.sh
</span></span></code></pre></div><h4 id="self-signed-certificate-testing-only">Self-Signed Certificate (Testing Only) <a class="anchor" data-pagefind-ignore href="#self-signed-certificate-testing-only" aria-label="Link to this section">#</a></h4>
<p>Creates a key, a certificate valid for a year and DH parameters in <code>/etc/bind/tls</code>, with the same names and permissions as above.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># Generate self-signed certificate for testing</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">mkdir -p /etc/bind/tls
</span></span><span class="line"><span class="cl"><span class="nb">cd</span> /etc/bind/tls
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate private key</span>
</span></span><span class="line"><span class="cl">openssl genrsa -out key.pem <span class="m">4096</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate certificate signing request</span>
</span></span><span class="line"><span class="cl">openssl req -new -key key.pem -out cert.csr <span class="se">\
</span></span></span><span class="line"><span class="cl">    -subj <span class="s2">&#34;/CN=dns.example.com/O=Example/C=US&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Self-sign certificate (valid for 365 days)</span>
</span></span><span class="line"><span class="cl">openssl x509 -req -days <span class="m">365</span> -in cert.csr <span class="se">\
</span></span></span><span class="line"><span class="cl">    -signkey key.pem -out cert.pem
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate DH parameters (optional but recommended)</span>
</span></span><span class="line"><span class="cl">openssl dhparam -out dhparam.pem <span class="m">2048</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Set permissions</span>
</span></span><span class="line"><span class="cl">chown bind:bind *.pem
</span></span><span class="line"><span class="cl">chmod <span class="m">640</span> *.pem
</span></span></code></pre></div><h2 id="dot-forwarding-configuration">DoT Forwarding Configuration <a class="anchor" data-pagefind-ignore href="#dot-forwarding-configuration" aria-label="Link to this section">#</a></h2>
<p>The other direction: BIND sends its own upstream queries over DoT. Use it when you forward to a public resolver and do not want your ISP to see those queries. This needs BIND 9.20+.</p>
<ul>
<li><code>forward only</code>: never fall back to plain recursion. If the DoT forwarders fail, clients get SERVFAIL.</li>
<li><code>forwarders port 853 tls upstream-dot</code>: send queries to these servers over TLS, checked with the <code>upstream-dot</code> block.</li>
<li><code>ca-file</code>: the CA bundle used to verify the upstream certificate.</li>
<li><code>remote-hostname</code>: the name that must be in the upstream certificate. Without it, the connection is encrypted but you do not know who you are talking to.</li>
</ul>
<pre tabindex="0"><code class="language-named" data-lang="named">// /etc/bind/named.conf.options

options {
    directory &#34;/var/cache/bind&#34;;
    
    // Listen for queries from local network
    listen-on { 127.0.0.1; 192.168.1.1; };
    listen-on-v6 { ::1; };
    
    recursion yes;
    allow-recursion { localhost; 192.168.0.0/16; };
    
    // Forward all queries via DoT (BIND 9.20+)
    forward only;
    forwarders port 853 tls upstream-dot {
        1.1.1.1;          // Cloudflare
        1.0.0.1;          // Cloudflare secondary
    };
    
    dnssec-validation auto;
};

// TLS configuration for upstream servers
tls upstream-dot {
    // CA bundle for verifying upstream certificates
    ca-file &#34;/etc/ssl/certs/ca-certificates.crt&#34;;
    
    // Hostname verification (important for security)
    remote-hostname &#34;cloudflare-dns.com&#34;;
    
    // Only use TLS 1.2 and 1.3
    protocols { TLSv1.2; TLSv1.3; };
};
</code></pre><p><code>remote-hostname</code> is checked against every server that uses this <code>tls</code> block, so only list servers that present that certificate name. Adding Google or Quad9 here makes their certificate checks fail, and with <code>forward only</code> the resolver then returns SERVFAIL. BIND 9.18 does not accept <code>tls</code> on <code>forwarders</code> at all; it is a syntax error there.</p>
<h3 id="multiple-upstream-providers-with-different-tls-settings">Multiple Upstream Providers with Different TLS Settings <a class="anchor" data-pagefind-ignore href="#multiple-upstream-providers-with-different-tls-settings" aria-label="Link to this section">#</a></h3>
<p>The fix for that limitation: one <code>tls</code> block per provider, each with its own <code>remote-hostname</code>. A forward zone can then use a different provider than the global forwarders.</p>
<table>
	<thead>
			<tr>
					<th>Setting</th>
					<th>Behaviour when the forwarders fail</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>forward only</code></td>
					<td>SERVFAIL</td>
					<td>Queries must never leave unencrypted</td>
			</tr>
			<tr>
					<td><code>forward first</code></td>
					<td>BIND resolves the query itself, from the root servers, without TLS</td>
					<td>Availability matters more than privacy</td>
			</tr>
	</tbody>
</table>
<pre tabindex="0"><code class="language-named" data-lang="named">// Different TLS configs for different providers
tls cloudflare-tls {
    ca-file &#34;/etc/ssl/certs/ca-certificates.crt&#34;;
    remote-hostname &#34;cloudflare-dns.com&#34;;
};

tls google-tls {
    ca-file &#34;/etc/ssl/certs/ca-certificates.crt&#34;;
    remote-hostname &#34;dns.google&#34;;
};

tls quad9-tls {
    ca-file &#34;/etc/ssl/certs/ca-certificates.crt&#34;;
    remote-hostname &#34;dns.quad9.net&#34;;
};

options {
    // Primary: Cloudflare
    forwarders port 853 tls cloudflare-tls {
        1.1.1.1;
        1.0.0.1;
    };
    
    forward first;  // Fall back to root servers if forwarders fail
};

// Alternative: Split forwarding by zone
zone &#34;example.com&#34; {
    type forward;
    forward only;
    forwarders port 853 tls google-tls { 8.8.8.8; };
};
</code></pre><h2 id="dot-with-stunnel-for-older-bind-versions">DoT with stunnel (For Older BIND Versions) <a class="anchor" data-pagefind-ignore href="#dot-with-stunnel-for-older-bind-versions" aria-label="Link to this section">#</a></h2>
<p>If running BIND &lt; 9.18 (or BIND 9.18, which cannot forward over DoT), use stunnel as a TLS wrapper. stunnel handles the TLS; BIND keeps talking plain DNS on the local host.</p>
<h3 id="stunnel-server-configuration">stunnel Server Configuration <a class="anchor" data-pagefind-ignore href="#stunnel-server-configuration" aria-label="Link to this section">#</a></h3>
<p>Accepts DoT on port 853 and passes the decrypted queries to BIND on <code>127.0.0.1:53</code>. Use this for the listener side on BIND &lt; 9.18.</p>
<ul>
<li><code>accept</code> / <code>connect</code>: the TLS port, and where the plain queries go.</li>
<li><code>options = NO_SSLv2</code> / <code>NO_SSLv3</code> and <code>sslVersion</code>: keep old protocols out.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-ini" data-lang="ini"><span class="line"><span class="cl"><span class="c1">; /etc/stunnel/dns-dot.conf</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">; Global settings</span>
</span></span><span class="line"><span class="cl"><span class="na">setuid</span> <span class="o">=</span> <span class="s">stunnel4</span>
</span></span><span class="line"><span class="cl"><span class="na">setgid</span> <span class="o">=</span> <span class="s">stunnel4</span>
</span></span><span class="line"><span class="cl"><span class="na">pid</span> <span class="o">=</span> <span class="s">/var/run/stunnel4/dns-dot.pid</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">; Logging</span>
</span></span><span class="line"><span class="cl"><span class="na">output</span> <span class="o">=</span> <span class="s">/var/log/stunnel4/dns-dot.log</span>
</span></span><span class="line"><span class="cl"><span class="na">debug</span> <span class="o">=</span> <span class="s">notice</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">; DoT server - accepts TLS connections, forwards to local BIND</span>
</span></span><span class="line"><span class="cl"><span class="k">[dns-dot-server]</span>
</span></span><span class="line"><span class="cl"><span class="na">accept</span> <span class="o">=</span> <span class="s">853</span>
</span></span><span class="line"><span class="cl"><span class="na">connect</span> <span class="o">=</span> <span class="s">127.0.0.1:53</span>
</span></span><span class="line"><span class="cl"><span class="na">cert</span> <span class="o">=</span> <span class="s">/etc/stunnel/cert.pem</span>
</span></span><span class="line"><span class="cl"><span class="na">key</span> <span class="o">=</span> <span class="s">/etc/stunnel/key.pem</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">; TLS options</span>
</span></span><span class="line"><span class="cl"><span class="na">options</span> <span class="o">=</span> <span class="s">NO_SSLv2</span>
</span></span><span class="line"><span class="cl"><span class="na">options</span> <span class="o">=</span> <span class="s">NO_SSLv3</span>
</span></span><span class="line"><span class="cl"><span class="na">options</span> <span class="o">=</span> <span class="s">SINGLE_DH_USE</span>
</span></span><span class="line"><span class="cl"><span class="na">options</span> <span class="o">=</span> <span class="s">SINGLE_ECDH_USE</span>
</span></span><span class="line"><span class="cl"><span class="na">ciphers</span> <span class="o">=</span> <span class="s">ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">; Protocol version</span>
</span></span><span class="line"><span class="cl"><span class="na">sslVersion</span> <span class="o">=</span> <span class="s">TLSv1.2</span>
</span></span></code></pre></div><h3 id="stunnel-client-configuration-dot-forwarding">stunnel Client Configuration (DoT Forwarding) <a class="anchor" data-pagefind-ignore href="#stunnel-client-configuration-dot-forwarding" aria-label="Link to this section">#</a></h3>
<p>The forwarding side. Each section gives one upstream DoT server a local plain address (<code>127.0.0.2</code>, <code>127.0.0.3</code>) that BIND can forward to.</p>
<ul>
<li><code>client = yes</code>: stunnel opens the TLS connection instead of accepting it.</li>
<li><code>verifyChain</code>, <code>CAfile</code>, <code>checkHost</code>: verify the upstream certificate and its name, like <code>remote-hostname</code> in BIND.</li>
</ul>
<p>Because each section has its own <code>checkHost</code>, mixing providers works here.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-ini" data-lang="ini"><span class="line"><span class="cl"><span class="c1">; /etc/stunnel/dns-dot-client.conf</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">[dns-dot-cloudflare]</span>
</span></span><span class="line"><span class="cl"><span class="c1">; Local plain DNS listener</span>
</span></span><span class="line"><span class="cl"><span class="na">accept</span> <span class="o">=</span> <span class="s">127.0.0.2:53</span>
</span></span><span class="line"><span class="cl"><span class="c1">; Remote DoT server</span>
</span></span><span class="line"><span class="cl"><span class="na">connect</span> <span class="o">=</span> <span class="s">1.1.1.1:853</span>
</span></span><span class="line"><span class="cl"><span class="na">client</span> <span class="o">=</span> <span class="s">yes</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">; Verify server certificate</span>
</span></span><span class="line"><span class="cl"><span class="na">verifyChain</span> <span class="o">=</span> <span class="s">yes</span>
</span></span><span class="line"><span class="cl"><span class="na">CAfile</span> <span class="o">=</span> <span class="s">/etc/ssl/certs/ca-certificates.crt</span>
</span></span><span class="line"><span class="cl"><span class="na">checkHost</span> <span class="o">=</span> <span class="s">cloudflare-dns.com</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">[dns-dot-google]</span>
</span></span><span class="line"><span class="cl"><span class="na">accept</span> <span class="o">=</span> <span class="s">127.0.0.3:53</span>
</span></span><span class="line"><span class="cl"><span class="na">connect</span> <span class="o">=</span> <span class="s">8.8.8.8:853</span>
</span></span><span class="line"><span class="cl"><span class="na">client</span> <span class="o">=</span> <span class="s">yes</span>
</span></span><span class="line"><span class="cl"><span class="na">verifyChain</span> <span class="o">=</span> <span class="s">yes</span>
</span></span><span class="line"><span class="cl"><span class="na">CAfile</span> <span class="o">=</span> <span class="s">/etc/ssl/certs/ca-certificates.crt</span>
</span></span><span class="line"><span class="cl"><span class="na">checkHost</span> <span class="o">=</span> <span class="s">dns.google</span>
</span></span></code></pre></div><p>Then configure BIND to forward to stunnel. The <code>server</code> statements make BIND use TCP towards the proxies:</p>
<pre tabindex="0"><code class="language-named" data-lang="named">// Forward to local stunnel proxies
options {
    forwarders {
        127.0.0.2;  // stunnel -&gt; Cloudflare DoT
        127.0.0.3;  // stunnel -&gt; Google DoT
    };
    forward only;
};

// stunnel only accepts TCP, so make BIND use TCP towards it
server 127.0.0.2 { tcp-only yes; };
server 127.0.0.3 { tcp-only yes; };
</code></pre><h2 id="performance-optimization">Performance Optimization <a class="anchor" data-pagefind-ignore href="#performance-optimization" aria-label="Link to this section">#</a></h2>
<p>DoT runs over TCP with a TLS handshake per connection. Performance comes down to keeping connections open and reusing them.</p>
<h3 id="connection-pooling">Connection Pooling <a class="anchor" data-pagefind-ignore href="#connection-pooling" aria-label="Link to this section">#</a></h3>
<ul>
<li><code>tcp-keepalive-timeout 600</code>: idle connections stay open for 60 seconds, so a client can send its next query without a new handshake.</li>
<li><code>tcp-clients 2000</code>: room for more open connections. Each costs memory, so size it to your client count.</li>
</ul>
<p>The TCP fast open comment is only a reminder: it is a kernel setting, not a BIND option.</p>
<pre tabindex="0"><code class="language-named" data-lang="named">options {
    // Keep TCP/TLS connections open longer (units of 100 ms: 600 = 60 seconds)
    tcp-keepalive-timeout 600;
    
    // Allow more concurrent TCP/TLS connections
    tcp-clients 2000;
    
    // Enable TCP fast open if supported
    // (kernel must support it: sysctl net.ipv4.tcp_fastopen=3)
};
</code></pre><h3 id="query-pipelining">Query Pipelining <a class="anchor" data-pagefind-ignore href="#query-pipelining" aria-label="Link to this section">#</a></h3>
<p>Modern DoT clients can send multiple queries over a single TLS connection. On the BIND side the one TLS setting that helps is <code>session-tickets</code>: a client that does reconnect resumes its session instead of doing a full handshake.</p>
<pre tabindex="0"><code class="language-named" data-lang="named">tls local-tls {
    cert-file &#34;/etc/bind/tls/cert.pem&#34;;
    key-file &#34;/etc/bind/tls/key.pem&#34;;
    
    // Enable session resumption for faster reconnects
    session-tickets yes;
};
</code></pre><h3 id="monitoring-dot-performance">Monitoring DoT Performance <a class="anchor" data-pagefind-ignore href="#monitoring-dot-performance" aria-label="Link to this section">#</a></h3>
<p>Quick checks from a client: a DoT query with <code>kdig</code> and with <code>dog</code>, and the TLS protocol and cipher the server negotiates.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># Test DoT response time</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">DOT_SERVER</span><span class="o">=</span><span class="s2">&#34;dns.example.com&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test with kdig (knot-dnsutils)</span>
</span></span><span class="line"><span class="cl">kdig +tls @<span class="nv">$DOT_SERVER</span> example.com A
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Measure TLS handshake time</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="p">|</span> openssl s_client -connect <span class="nv">$DOT_SERVER</span>:853 2&gt;<span class="p">&amp;</span><span class="m">1</span> <span class="p">|</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    grep -E <span class="s2">&#34;(Verify return|Protocol|Cipher)&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test with dog (modern dig alternative)</span>
</span></span><span class="line"><span class="cl">dog --tls @<span class="nv">$DOT_SERVER</span> example.com A
</span></span></code></pre></div><h2 id="firewall-configuration">Firewall Configuration <a class="anchor" data-pagefind-ignore href="#firewall-configuration" aria-label="Link to this section">#</a></h2>
<p>Open TCP 853 inbound for clients and outbound if you forward over DoT. Both versions below also limit each source address to about 100 new DoT connections a minute, so one client cannot exhaust <code>tcp-clients</code>. The rate limit must come before the accept rule.</p>
<h3 id="iptables-rules">iptables Rules <a class="anchor" data-pagefind-ignore href="#iptables-rules" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># Allow DoT traffic</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Rate limiting to prevent abuse (must come before the ACCEPT rule)</span>
</span></span><span class="line"><span class="cl">iptables -A INPUT -p tcp --dport <span class="m">853</span> -m state --state NEW <span class="se">\
</span></span></span><span class="line"><span class="cl">    -m recent --set --name DOT
</span></span><span class="line"><span class="cl">iptables -A INPUT -p tcp --dport <span class="m">853</span> -m state --state NEW <span class="se">\
</span></span></span><span class="line"><span class="cl">    -m recent --update --seconds <span class="m">60</span> --hitcount <span class="m">100</span> --name DOT -j DROP
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Allow incoming DoT (port 853)</span>
</span></span><span class="line"><span class="cl">iptables -A INPUT -p tcp --dport <span class="m">853</span> -j ACCEPT
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Allow outgoing DoT to upstream resolvers</span>
</span></span><span class="line"><span class="cl">iptables -A OUTPUT -p tcp --dport <span class="m">853</span> -j ACCEPT
</span></span></code></pre></div><h3 id="nftables-rules">nftables Rules <a class="anchor" data-pagefind-ignore href="#nftables-rules" aria-label="Link to this section">#</a></h3>
<pre tabindex="0"><code class="language-nftables" data-lang="nftables">#!/usr/sbin/nft -f

table inet filter {
    chain input {
        type filter hook input priority 0; policy accept;

        # Rate limit new DoT connections (must come before the accept)
        tcp dport 853 ct state new meter dot-meter { ip saddr limit rate over 100/minute } drop

        # Allow DoT
        tcp dport 853 accept
    }
    
    chain output {
        type filter hook output priority 0; policy accept;

        # Allow outgoing DoT
        tcp dport 853 accept
    }
}
</code></pre><h2 id="client-configuration">Client Configuration <a class="anchor" data-pagefind-ignore href="#client-configuration" aria-label="Link to this section">#</a></h2>
<p>A client must know two things: the resolver&rsquo;s address and the name in its certificate. Without the name it cannot verify the server.</p>
<table>
	<thead>
			<tr>
					<th>Client</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>systemd-resolved</td>
					<td>Linux desktops and servers that already use it</td>
			</tr>
			<tr>
					<td>Android Private DNS</td>
					<td>Phones (needs a hostname, not an IP)</td>
			</tr>
			<tr>
					<td>Stubby</td>
					<td>Any system: a local stub that speaks plain DNS to apps and DoT upstream</td>
			</tr>
	</tbody>
</table>
<h3 id="systemd-resolved">systemd-resolved <a class="anchor" data-pagefind-ignore href="#systemd-resolved" aria-label="Link to this section">#</a></h3>
<ul>
<li><code>DNS=192.168.1.1#dns.example.com</code>: the address, and after <code>#</code> the name to verify in the certificate.</li>
<li><code>DNSOverTLS=yes</code>: strict mode. If TLS fails, resolution fails. <code>opportunistic</code> falls back to plain DNS instead.</li>
<li><code>DNSSEC=yes</code>: validate answers as well.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-ini" data-lang="ini"><span class="line"><span class="cl"><span class="c1"># /etc/systemd/resolved.conf</span>
</span></span><span class="line"><span class="cl"><span class="k">[Resolve]</span>
</span></span><span class="line"><span class="cl"><span class="na">DNS</span><span class="o">=</span><span class="s">192.168.1.1#dns.example.com</span>
</span></span><span class="line"><span class="cl"><span class="na">DNSOverTLS</span><span class="o">=</span><span class="s">yes</span>
</span></span><span class="line"><span class="cl"><span class="na">DNSSEC</span><span class="o">=</span><span class="s">yes</span>
</span></span></code></pre></div><h3 id="android-private-dns">Android Private DNS <a class="anchor" data-pagefind-ignore href="#android-private-dns" aria-label="Link to this section">#</a></h3>
<ol>
<li>Settings -&gt; Network &amp; Internet -&gt; Advanced -&gt; Private DNS</li>
<li>Enter: <code>dns.example.com</code></li>
</ol>
<h3 id="stubby-general-purpose-dot-client">Stubby (General-Purpose DoT Client) <a class="anchor" data-pagefind-ignore href="#stubby-general-purpose-dot-client" aria-label="Link to this section">#</a></h3>
<ul>
<li><code>dns_transport_list: GETDNS_TRANSPORT_TLS</code> with <code>tls_authentication: GETDNS_AUTHENTICATION_REQUIRED</code>: TLS only, with a valid certificate. No plain fallback.</li>
<li><code>tls_query_padding_blocksize</code>: pads queries to a fixed block size, so their length gives less away.</li>
<li><code>listen_addresses</code>: where local applications (or a local BIND) send plain queries.</li>
<li><code>tls_auth_name</code>: the name checked in the resolver&rsquo;s certificate.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="c"># /etc/stubby/stubby.yml</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">resolution_type</span><span class="p">:</span><span class="w"> </span><span class="l">GETDNS_RESOLUTION_STUB</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">dns_transport_list</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="l">GETDNS_TRANSPORT_TLS</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">tls_authentication</span><span class="p">:</span><span class="w"> </span><span class="l">GETDNS_AUTHENTICATION_REQUIRED</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">tls_query_padding_blocksize</span><span class="p">:</span><span class="w"> </span><span class="m">128</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">edns_client_subnet_private</span><span class="p">:</span><span class="w"> </span><span class="m">1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">idle_timeout</span><span class="p">:</span><span class="w"> </span><span class="m">10000</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">listen_addresses</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="m">127.0.0.1</span>@<span class="m">53000</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">upstream_recursive_servers</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">address_data</span><span class="p">:</span><span class="w"> </span><span class="m">192.168.1.1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">tls_auth_name</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;dns.example.com&#34;</span><span class="w">
</span></span></span></code></pre></div><h2 id="complete-production-configuration">Complete Production Configuration <a class="anchor" data-pagefind-ignore href="#complete-production-configuration" aria-label="Link to this section">#</a></h2>
<p>Here&rsquo;s a complete DoT-enabled resolver configuration. It combines the pieces above and adds:</p>
<ul>
<li><code>acl trusted</code> with <code>allow-query</code> and <code>allow-recursion</code>: only your networks may use the resolver, over port 53 or 853.</li>
<li><code>version none</code> and <code>hostname none</code>: do not reveal the BIND version or host name to <code>CHAOS</code> queries.</li>
<li>Upstream DoT forwarding, commented out. Enable it on BIND 9.20+.</li>
<li>A <code>tls_log</code> channel for the <code>network</code> category, for connection problems.</li>
</ul>
<pre tabindex="0"><code class="language-named" data-lang="named">// /etc/bind/named.conf

acl trusted {
    localhost;
    192.168.0.0/16;
    10.0.0.0/8;
};

options {
    directory &#34;/var/cache/bind&#34;;
    
    // Standard DNS
    listen-on { 127.0.0.1; 192.168.1.1; };
    listen-on-v6 { ::1; };
    
    // DNS over TLS
    listen-on port 853 tls dot-server { 127.0.0.1; 192.168.1.1; };
    listen-on-v6 port 853 tls dot-server { ::1; };
    
    // Access control
    allow-query { trusted; };
    allow-recursion { trusted; };
    recursion yes;
    
    // DNSSEC
    dnssec-validation auto;
    
    // Performance
    tcp-clients 2000;
    tcp-keepalive-timeout 600;    // units of 100 ms: 600 = 60 seconds
    
    // Security
    version none;
    hostname none;
    
    // Forward to upstream DoT (optional, BIND 9.20+)
    // forwarders port 853 tls upstream-dot { 1.1.1.1; 1.0.0.1; };
    // forward first;
};

// Server TLS configuration
tls dot-server {
    cert-file &#34;/etc/bind/tls/cert.pem&#34;;
    key-file &#34;/etc/bind/tls/key.pem&#34;;
    dhparam-file &#34;/etc/bind/tls/dhparam.pem&#34;;
    protocols { TLSv1.2; TLSv1.3; };
    ciphers &#34;ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305&#34;;
    prefer-server-ciphers yes;
    session-tickets yes;
};

// Upstream DoT configuration (for forwarding)
tls upstream-dot {
    ca-file &#34;/etc/ssl/certs/ca-certificates.crt&#34;;
    remote-hostname &#34;cloudflare-dns.com&#34;;
    protocols { TLSv1.2; TLSv1.3; };
};

logging {
    channel tls_log {
        file &#34;/var/log/named/tls.log&#34; versions 5 size 10m;
        severity info;
        print-time yes;
        print-category yes;
    };
    category network { tls_log; };
};
</code></pre><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<h3 id="test-dot-connectivity">Test DoT Connectivity <a class="anchor" data-pagefind-ignore href="#test-dot-connectivity" aria-label="Link to this section">#</a></h3>
<p>Start from the client: does a DoT query work, and what does the TLS handshake show?</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Test with kdig</span>
</span></span><span class="line"><span class="cl">kdig +tls @dns.example.com example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test with openssl</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> -e <span class="s2">&#34;\x00\x1e\x00\x00\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00\x07example\x03com\x00\x00\x01\x00\x01&#34;</span> <span class="p">|</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    openssl s_client -connect dns.example.com:853 -quiet
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Verbose TLS handshake</span>
</span></span><span class="line"><span class="cl">openssl s_client -connect dns.example.com:853 -status -tlsextdebug
</span></span></code></pre></div><h3 id="common-issues">Common Issues <a class="anchor" data-pagefind-ignore href="#common-issues" aria-label="Link to this section">#</a></h3>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Likely cause</th>
					<th>Check</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Client reports a certificate error</td>
					<td>Expired certificate, missing intermediate, or wrong name</td>
					<td>Certificate commands below</td>
			</tr>
			<tr>
					<td>BIND does not start after adding <code>tls</code></td>
					<td>BIND cannot read the key or certificate</td>
					<td>Permission commands below</td>
			</tr>
			<tr>
					<td>Connection refused on 853</td>
					<td>No listener, or the firewall drops it</td>
					<td>Connection commands below</td>
			</tr>
			<tr>
					<td>SERVFAIL with DoT forwarding</td>
					<td><code>remote-hostname</code> does not match an upstream&rsquo;s certificate</td>
					<td>One <code>tls</code> block per provider</td>
			</tr>
	</tbody>
</table>
<p><strong>Certificate errors:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check certificate validity</span>
</span></span><span class="line"><span class="cl">openssl x509 -in /etc/bind/tls/cert.pem -text -noout <span class="p">|</span> grep -A2 Validity
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Verify certificate chain (cert.pem is the full chain, pass it as -untrusted for the intermediate)</span>
</span></span><span class="line"><span class="cl">openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt -untrusted /etc/bind/tls/cert.pem /etc/bind/tls/cert.pem
</span></span></code></pre></div><p><strong>Permission errors:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Ensure BIND can read certificates</span>
</span></span><span class="line"><span class="cl">ls -la /etc/bind/tls/
</span></span><span class="line"><span class="cl">chown bind:bind /etc/bind/tls/*.pem
</span></span><span class="line"><span class="cl">chmod <span class="m">640</span> /etc/bind/tls/*.pem
</span></span></code></pre></div><p><strong>Connection refused:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check if BIND is listening on 853</span>
</span></span><span class="line"><span class="cl">ss -tlnp <span class="p">|</span> grep <span class="m">853</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check firewall</span>
</span></span><span class="line"><span class="cl">iptables -L INPUT -n <span class="p">|</span> grep <span class="m">853</span>
</span></span></code></pre></div><h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Use valid certificates</strong>: self-signed certificates don&rsquo;t provide authentication.</li>
<li><strong>Enable DNSSEC</strong>: DoT encrypts transport, DNSSEC authenticates content.</li>
<li><strong>Restrict TLS versions</strong>: only allow TLS 1.2 and 1.3.</li>
<li><strong>Monitor certificate expiry</strong>: set up alerts before certificates expire.</li>
<li><strong>Use strong cipher suites</strong>: prefer ECDHE for forward secrecy.</li>
<li><strong>Rate limit connections</strong>: prevent DoS attacks on port 853.</li>
<li><strong>Log TLS events</strong>: monitor for connection failures and attacks.</li>
<li><strong>Mind <code>forward first</code></strong>: when the DoT forwarders fail, queries leave unencrypted.</li>
</ul>
<h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub: <a href="https://github.com/pderuiter/blog-bind-dot-secure" rel="noopener">pderuiter/blog-bind-dot-secure</a>. It creates an Ubuntu 24.04 VM on Proxmox and configures BIND with the DoT listener from the complete configuration above, with optional DoT forwarding to Cloudflare (BIND 9.20 from the ISC packages) and the nftables rate limit; run <code>terraform apply</code> and then <code>ansible-playbook site.yml</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>With BIND 9.18+ the DoT listener is native; DoT forwarding needs 9.20+. On older versions, stunnel does the TLS for BIND.</p>
<p>Key takeaways:</p>
<ul>
<li>Use valid TLS certificates from a trusted CA</li>
<li>Enable both server-side DoT (for clients) and client-side DoT (for upstream forwarding)</li>
<li>Set <code>remote-hostname</code> per upstream provider</li>
<li>Monitor and maintain certificate renewals</li>
</ul>
<p>The next post will cover DNS over HTTPS (DoH), which provides similar encryption using HTTPS and is increasingly supported by browsers and applications.</p>
]]></content:encoded></item><item><title>Implementing DNS over HTTPS (DoH) with BIND and nginx</title><link>https://blog.bsdserver.nl/implementing-dns-over-https-doh-with-bind-and-nginx/</link><guid isPermaLink="false">693b6f2679eb54000160a5b5</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:25:58 +0000</pubDate><description>First, a short side note. Personal viewpoint: I’m not a fan of DNS over HTTPS (DoH).</description><category>BIND</category><category>DNS</category><category>DNS over HTTPS</category><category>HTTPS</category><category>Security</category><category>nginx</category><category>Encryption</category><category>Homelab</category><category>Linux</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/dns-over-https-with-bind-and-nginx.png" medium="image"/><content:encoded><![CDATA[<p>First, a short side note.</p>
<p><strong>Personal viewpoint:</strong> I’m not a fan of DNS over HTTPS (DoH). The main reason is not encryption itself (encryption is a good thing) but <em>how</em> DoH is implemented and deployed.</p>
<p><strong>Facts:</strong></p>
<ul>
<li>DoH carries DNS inside regular HTTPS traffic (TCP/443), indistinguishable from normal web traffic. Firewall rules, DNS logging, traffic inspection and policy enforcement become much harder, or impossible without TLS interception.</li>
<li>DNS over TLS (DoT) uses a dedicated port (TCP/853). It is just as encrypted, but easy to identify, monitor, rate-limit or block at the network edge.</li>
<li>Major public DoH providers include Google, Cloudflare and others. Clients that use them outsource resolution to a third party, which then holds query timing, source IPs (or coarse location) and domain access patterns. That data is valuable for analytics and profiling, whatever the privacy promises.</li>
<li>DoH bypasses split-horizon DNS, ignores local policy tools (RPZ, DNS firewalling, internal blocklists) and complicates incident response, since DNS activity hides inside generic HTTPS flows.</li>
</ul>
<p><strong>Personal viewpoint (clearly marked):</strong> This centralisation is what I’m uncomfortable with. DoT still lets organisations run their <em>own</em> encrypted resolvers without losing visibility. I actively block DoH in my environments using Response Policy Zones (RPZ) in BIND, and support encrypted DNS via DoT where it makes sense.</p>
<p>In short: encryption is not the problem. <strong>Loss of control, visibility, and centralisation of data at a few hyperscalers is.</strong></p>
<h2 id="what-is-dns-over-https">What is DNS over HTTPS? <a class="anchor" data-pagefind-ignore href="#what-is-dns-over-https" aria-label="Link to this section">#</a></h2>
<p>DNS over HTTPS (DoH) encrypts DNS queries within regular HTTPS traffic, making them indistinguishable from normal web browsing. This provides privacy benefits but requires a different architectural approach than DoT.</p>
<p>If your clients are going to use DoH anyway, it is better that they use <em>your</em> resolver. This post puts a DoH front end on your BIND resolver, with nginx as a reverse proxy, so your own policies (RPZ, split horizon, logging) still apply.</p>
<h2 id="why-doh">Why DoH? <a class="anchor" data-pagefind-ignore href="#why-doh" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Advantages/Disadvantages</th>
					<th>Description</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Privacy</td>
					<td>ISPs cannot see DNS queries</td>
			</tr>
			<tr>
					<td>Censorship resistance</td>
					<td>Hard to block (uses port 443)</td>
			</tr>
			<tr>
					<td>Browser integration</td>
					<td>Native support in Firefox, Chrome</td>
			</tr>
			<tr>
					<td>Enterprise bypass</td>
					<td>Can bypass network DNS policies</td>
			</tr>
	</tbody>
</table>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> when browsers or apps on your network expect DoH, or for roaming clients that must reach your resolver over networks that only allow HTTPS.</li>
<li><strong>Skip it</strong> when you control the clients: DoT (or plain DNS on a trusted network) is simpler to operate and to monitor.</li>
</ul>
<h2 id="understanding-dns-over-https">Understanding DNS over HTTPS <a class="anchor" data-pagefind-ignore href="#understanding-dns-over-https" aria-label="Link to this section">#</a></h2>
<h3 id="how-doh-works">How DoH Works <a class="anchor" data-pagefind-ignore href="#how-doh-works" aria-label="Link to this section">#</a></h3>
<p>DoH encapsulates DNS queries in HTTP/2 requests over TLS:</p>
<ol>
<li>Client sends DNS query as HTTP POST or GET to <code>/dns-query</code></li>
<li>Query encoded as <code>application/dns-message</code> (RFC 8484)</li>
<li>Response returned as HTTP response body</li>
<li>All traffic flows over standard HTTPS (port 443)</li>
</ol>
<p>With GET, the query goes base64url-encoded in the <code>?dns=</code> parameter; with POST, it is the raw request body.</p>
<h3 id="wire-format-vs-json">Wire Format vs JSON <a class="anchor" data-pagefind-ignore href="#wire-format-vs-json" aria-label="Link to this section">#</a></h3>
<p>DoH supports two formats:</p>
<table>
	<thead>
			<tr>
					<th></th>
					<th>Wire format (RFC 8484)</th>
					<th>JSON (Google/Cloudflare JSON API, not part of RFC 8484)</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Content-Type</td>
					<td><code>application/dns-message</code></td>
					<td><code>application/dns-json</code></td>
			</tr>
			<tr>
					<td>Content</td>
					<td>Standard DNS binary format over HTTP</td>
					<td>Human-readable JSON</td>
			</tr>
			<tr>
					<td>Strengths</td>
					<td>More efficient, widely supported</td>
					<td>Easier to debug and inspect</td>
			</tr>
			<tr>
					<td>Used by</td>
					<td>Browsers and system resolvers</td>
					<td>Some API-based clients</td>
			</tr>
	</tbody>
</table>
<p>Serve wire format; JSON is optional (see <a href="#json-api-support">JSON API Support</a>).</p>
<h2 id="architecture-options">Architecture Options <a class="anchor" data-pagefind-ignore href="#architecture-options" aria-label="Link to this section">#</a></h2>
<p>BIND 9.18 and later can serve DoH natively with the <code>http</code> statement:</p>
<pre tabindex="0"><code>tls doh-cert {
    cert-file &#34;/etc/bind/tls/cert.pem&#34;;
    key-file &#34;/etc/bind/tls/key.pem&#34;;
};

http doh-local {
    endpoints { &#34;/dns-query&#34;; };
};

options {
    listen-on { any; };    // keep plain DNS on port 53
    listen-on port 443 tls doh-cert http doh-local { any; };
};
</code></pre><ul>
<li><code>tls doh-cert</code>: the certificate and key BIND uses.</li>
<li><code>http doh-local</code>: the URL path that accepts DoH requests.</li>
<li><code>listen-on port 443 tls ... http ...</code>: a second listener for DoH next to plain DNS on port 53.</li>
</ul>
<p>That is fine for a simple setup. This post uses a proxy layer in front of BIND instead, which gives you nginx&rsquo;s rate limiting, access control, caching and shared TLS termination with other sites:</p>
<pre tabindex="0"><code>Client --HTTPS--&gt; nginx (DoH) --DNS--&gt; BIND
</code></pre><p>There are three ways to build that proxy layer:</p>
<table>
	<thead>
			<tr>
					<th>Option</th>
					<th>How</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>1. nginx with Lua (OpenResty)</td>
					<td>nginx itself forwards the query to BIND</td>
					<td>Experiments; you maintain the Lua code</td>
			</tr>
			<tr>
					<td>2. dnsdist</td>
					<td>dnsdist terminates TLS and forwards to BIND</td>
					<td>Simplest setup; also serves DoT</td>
			</tr>
			<tr>
					<td>3. doh-server + nginx</td>
					<td>nginx terminates TLS, doh-server translates HTTP to DNS</td>
					<td>Flexible production setup, used in the rest of this post</td>
			</tr>
	</tbody>
</table>
<p>We&rsquo;ll cover all three approaches.</p>
<h2 id="prerequisites">Prerequisites <a class="anchor" data-pagefind-ignore href="#prerequisites" aria-label="Link to this section">#</a></h2>
<ul>
<li>Working BIND resolver accepting queries on localhost</li>
<li>nginx with HTTP/2 support</li>
<li>Valid TLS certificate</li>
<li>Port 443 available (or separate IP/hostname)</li>
</ul>
<h2 id="option-1-nginx-with-dns-proxy-module">Option 1: nginx with DNS Proxy Module <a class="anchor" data-pagefind-ignore href="#option-1-nginx-with-dns-proxy-module" aria-label="Link to this section">#</a></h2>
<p>nginx alone cannot translate HTTP into DNS. This option adds Lua scripting so nginx itself turns the HTTP request into a UDP DNS query to BIND.</p>
<h3 id="install-nginx-with-stream-module">Install nginx with Stream Module <a class="anchor" data-pagefind-ignore href="#install-nginx-with-stream-module" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Ubuntu/Debian - nginx comes with stream module</span>
</span></span><span class="line"><span class="cl">apt install nginx libnginx-mod-stream
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Verify stream module</span>
</span></span><span class="line"><span class="cl">nginx -V 2&gt;<span class="p">&amp;</span><span class="m">1</span> <span class="p">|</span> grep -o with-stream
</span></span></code></pre></div><h3 id="basic-doh-configuration-with-lua-resty-dns">Basic DoH Configuration with lua-resty-dns <a class="anchor" data-pagefind-ignore href="#basic-doh-configuration-with-lua-resty-dns" aria-label="Link to this section">#</a></h3>
<p>This requires nginx with Lua support (OpenResty or nginx-extras):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Install OpenResty</span>
</span></span><span class="line"><span class="cl">apt install -y gnupg
</span></span><span class="line"><span class="cl">curl -fsSL https://openresty.org/package/pubkey.gpg <span class="p">|</span> apt-key add -
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;deb http://openresty.org/package/ubuntu </span><span class="k">$(</span>lsb_release -sc<span class="k">)</span><span class="s2"> main&#34;</span> &gt; /etc/apt/sources.list.d/openresty.list
</span></span><span class="line"><span class="cl">apt update <span class="o">&amp;&amp;</span> apt install openresty
</span></span></code></pre></div><p>The configuration handles both request methods. GET decodes the base64url <code>dns</code> parameter; POST reads the binary body. Both send the query to BIND on <code>127.0.0.1:53</code> and return the reply as <code>application/dns-message</code>.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-nginx" data-lang="nginx"><span class="line"><span class="cl"><span class="c1"># /etc/openresty/nginx.conf
</span></span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">worker_processes</span> <span class="s">auto</span><span class="p">;</span>
</span></span><span class="line"><span class="cl"><span class="k">events</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="kn">worker_connections</span> <span class="mi">1024</span><span class="p">;</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">http</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># Upstream BIND resolver
</span></span></span><span class="line"><span class="cl">    <span class="kn">upstream</span> <span class="s">dns_backend</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="kn">server</span> <span class="n">127.0.0.1</span><span class="p">:</span><span class="mi">53</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># DoH server
</span></span></span><span class="line"><span class="cl">    <span class="kn">server</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="kn">listen</span> <span class="mi">443</span> <span class="s">ssl</span> <span class="s">http2</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">server_name</span> <span class="s">dns.example.com</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="kn">ssl_certificate</span> <span class="s">/etc/letsencrypt/live/dns.example.com/fullchain.pem</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">ssl_certificate_key</span> <span class="s">/etc/letsencrypt/live/dns.example.com/privkey.pem</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">ssl_protocols</span> <span class="s">TLSv1.2</span> <span class="s">TLSv1.3</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">ssl_ciphers</span> <span class="s">ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">ssl_prefer_server_ciphers</span> <span class="no">on</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="c1"># DoH endpoint
</span></span></span><span class="line"><span class="cl">        <span class="kn">location</span> <span class="s">/dns-query</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">            <span class="c1"># Handle GET requests (base64url encoded query in dns parameter)
</span></span></span><span class="line"><span class="cl">            <span class="kn">if</span> <span class="s">(</span><span class="nv">$request_method</span> <span class="p">=</span> <span class="s">GET)</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">                <span class="c1"># Process via Lua
</span></span></span><span class="line"><span class="cl">                <span class="kn">content_by_lua_block</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">                    <span class="kn">local</span> <span class="s">resolver</span> <span class="p">=</span> <span class="s">require</span> <span class="s">&#34;resty.dns.resolver&#34;</span>
</span></span><span class="line"><span class="cl">                    <span class="s">local</span> <span class="s">base64</span> <span class="p">=</span> <span class="s">require</span> <span class="s">&#34;ngx.base64&#34;</span>
</span></span><span class="line"><span class="cl">                    
</span></span><span class="line"><span class="cl">                    <span class="s">local</span> <span class="s">dns_query</span> <span class="p">=</span> <span class="s">ngx.var.arg_dns</span>
</span></span><span class="line"><span class="cl">                    <span class="s">if</span> <span class="s">not</span> <span class="s">dns_query</span> <span class="s">then</span>
</span></span><span class="line"><span class="cl">                        <span class="s">ngx.status</span> <span class="p">=</span> <span class="mi">400</span>
</span></span><span class="line"><span class="cl">                        <span class="s">ngx.say(&#34;Missing</span> <span class="s">dns</span> <span class="s">parameter&#34;)</span>
</span></span><span class="line"><span class="cl">                        <span class="s">return</span>
</span></span><span class="line"><span class="cl">                    <span class="s">end</span>
</span></span><span class="line"><span class="cl">                    
</span></span><span class="line"><span class="cl">                    <span class="s">--</span> <span class="s">Decode</span> <span class="s">base64url</span>
</span></span><span class="line"><span class="cl">                    <span class="s">local</span> <span class="s">query_data</span> <span class="p">=</span> <span class="s">base64.decode_base64url(dns_query)</span>
</span></span><span class="line"><span class="cl">                    
</span></span><span class="line"><span class="cl">                    <span class="s">--</span> <span class="s">Forward</span> <span class="s">to</span> <span class="s">BIND</span>
</span></span><span class="line"><span class="cl">                    <span class="s">local</span> <span class="s">sock</span> <span class="p">=</span> <span class="s">ngx.socket.udp()</span>
</span></span><span class="line"><span class="cl">                    <span class="s">sock:setpeername(&#34;127.0.0.1&#34;,</span> <span class="mi">53</span><span class="s">)</span>
</span></span><span class="line"><span class="cl">                    <span class="s">sock:send(query_data)</span>
</span></span><span class="line"><span class="cl">                    <span class="s">local</span> <span class="s">response</span> <span class="p">=</span> <span class="s">sock:receive()</span>
</span></span><span class="line"><span class="cl">                    <span class="s">sock:close()</span>
</span></span><span class="line"><span class="cl">                    
</span></span><span class="line"><span class="cl">                    <span class="s">ngx.header[&#34;Content-Type&#34;]</span> <span class="p">=</span> <span class="s">&#34;application/dns-message&#34;</span>
</span></span><span class="line"><span class="cl">                    <span class="s">ngx.print(response)</span>
</span></span><span class="line"><span class="cl">                <span class="err">}</span>
</span></span><span class="line"><span class="cl">            <span class="err">}</span>
</span></span><span class="line"><span class="cl">            
</span></span><span class="line"><span class="cl">            <span class="c1"># Handle POST requests (binary DNS query in body)
</span></span></span><span class="line"><span class="cl">            <span class="s">if</span> <span class="s">(</span><span class="nv">$request_method</span> <span class="p">=</span> <span class="s">POST)</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">                <span class="kn">content_by_lua_block</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">                    <span class="kn">ngx.req.read_body()</span>
</span></span><span class="line"><span class="cl">                    <span class="s">local</span> <span class="s">query_data</span> <span class="p">=</span> <span class="s">ngx.req.get_body_data()</span>
</span></span><span class="line"><span class="cl">                    
</span></span><span class="line"><span class="cl">                    <span class="s">if</span> <span class="s">not</span> <span class="s">query_data</span> <span class="s">then</span>
</span></span><span class="line"><span class="cl">                        <span class="s">ngx.status</span> <span class="p">=</span> <span class="mi">400</span>
</span></span><span class="line"><span class="cl">                        <span class="s">ngx.say(&#34;Empty</span> <span class="s">request</span> <span class="s">body&#34;)</span>
</span></span><span class="line"><span class="cl">                        <span class="s">return</span>
</span></span><span class="line"><span class="cl">                    <span class="s">end</span>
</span></span><span class="line"><span class="cl">                    
</span></span><span class="line"><span class="cl">                    <span class="s">--</span> <span class="s">Forward</span> <span class="s">to</span> <span class="s">BIND</span>
</span></span><span class="line"><span class="cl">                    <span class="s">local</span> <span class="s">sock</span> <span class="p">=</span> <span class="s">ngx.socket.udp()</span>
</span></span><span class="line"><span class="cl">                    <span class="s">sock:setpeername(&#34;127.0.0.1&#34;,</span> <span class="mi">53</span><span class="s">)</span>
</span></span><span class="line"><span class="cl">                    <span class="s">sock:send(query_data)</span>
</span></span><span class="line"><span class="cl">                    <span class="s">local</span> <span class="s">response</span> <span class="p">=</span> <span class="s">sock:receive()</span>
</span></span><span class="line"><span class="cl">                    <span class="s">sock:close()</span>
</span></span><span class="line"><span class="cl">                    
</span></span><span class="line"><span class="cl">                    <span class="s">ngx.header[&#34;Content-Type&#34;]</span> <span class="p">=</span> <span class="s">&#34;application/dns-message&#34;</span>
</span></span><span class="line"><span class="cl">                    <span class="s">ngx.print(response)</span>
</span></span><span class="line"><span class="cl">                <span class="err">}</span>
</span></span><span class="line"><span class="cl">            <span class="err">}</span>
</span></span><span class="line"><span class="cl">        <span class="err">}</span>
</span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="c1"># Health check endpoint
</span></span></span><span class="line"><span class="cl">        <span class="s">location</span> <span class="s">/health</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">            <span class="kn">return</span> <span class="mi">200</span> <span class="s">&#34;OK&#34;</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="p">}</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span></code></pre></div><h2 id="option-2-using-dnsdist-as-doh-frontend">Option 2: Using dnsdist as DoH Frontend <a class="anchor" data-pagefind-ignore href="#option-2-using-dnsdist-as-doh-frontend" aria-label="Link to this section">#</a></h2>
<p>dnsdist (from PowerDNS) is a DNS load balancer with built-in DoH and DoT support. It terminates TLS itself, so no nginx is involved; it needs port 443 for itself.</p>
<h3 id="install-dnsdist">Install dnsdist <a class="anchor" data-pagefind-ignore href="#install-dnsdist" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Ubuntu/Debian</span>
</span></span><span class="line"><span class="cl">apt install dnsdist
</span></span></code></pre></div><h3 id="configure-dnsdist-for-doh">Configure dnsdist for DoH <a class="anchor" data-pagefind-ignore href="#configure-dnsdist-for-doh" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-lua" data-lang="lua"><span class="line"><span class="cl"><span class="c1">-- /etc/dnsdist/dnsdist.conf</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">-- Backend BIND server</span>
</span></span><span class="line"><span class="cl"><span class="n">newServer</span><span class="p">({</span><span class="n">address</span><span class="o">=</span><span class="s2">&#34;127.0.0.1:53&#34;</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s2">&#34;bind-local&#34;</span><span class="p">})</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">-- DoH frontend</span>
</span></span><span class="line"><span class="cl"><span class="n">addDOHLocal</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">    <span class="s2">&#34;0.0.0.0:443&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="s2">&#34;/etc/letsencrypt/live/dns.example.com/fullchain.pem&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="s2">&#34;/etc/letsencrypt/live/dns.example.com/privkey.pem&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="p">{</span> <span class="s2">&#34;/dns-query&#34;</span> <span class="p">},</span>
</span></span><span class="line"><span class="cl">    <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="n">minTLSVersion</span> <span class="o">=</span> <span class="s2">&#34;tls1.2&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="n">ciphers</span> <span class="o">=</span> <span class="s2">&#34;ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="n">customResponseHeaders</span> <span class="o">=</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">            <span class="p">[</span><span class="s2">&#34;Cache-Control&#34;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&#34;max-age=300&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="p">}</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">-- Also serve DoT on 853</span>
</span></span><span class="line"><span class="cl"><span class="n">addTLSLocal</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">    <span class="s2">&#34;0.0.0.0:853&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="s2">&#34;/etc/letsencrypt/live/dns.example.com/fullchain.pem&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="s2">&#34;/etc/letsencrypt/live/dns.example.com/privkey.pem&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="n">minTLSVersion</span> <span class="o">=</span> <span class="s2">&#34;tls1.2&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">-- Access control</span>
</span></span><span class="line"><span class="cl"><span class="n">addACL</span><span class="p">(</span><span class="s2">&#34;192.168.0.0/16&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="n">addACL</span><span class="p">(</span><span class="s2">&#34;10.0.0.0/8&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="n">addACL</span><span class="p">(</span><span class="s2">&#34;127.0.0.0/8&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">-- Logging</span>
</span></span><span class="line"><span class="cl"><span class="n">addAction</span><span class="p">(</span><span class="n">AllRule</span><span class="p">(),</span> <span class="n">LogAction</span><span class="p">(</span><span class="s2">&#34;/var/log/dnsdist/queries.log&#34;</span><span class="p">,</span> <span class="kc">false</span><span class="p">,</span> <span class="kc">true</span><span class="p">))</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">-- Web interface for monitoring</span>
</span></span><span class="line"><span class="cl"><span class="n">webserver</span><span class="p">(</span><span class="s2">&#34;127.0.0.1:8083&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="n">setWebserverConfig</span><span class="p">({</span>
</span></span><span class="line"><span class="cl">    <span class="n">password</span> <span class="o">=</span> <span class="s2">&#34;secret-password&#34;</span><span class="p">,</span>   <span class="c1">-- or a hash from hashPassword()</span>
</span></span><span class="line"><span class="cl">    <span class="n">acl</span> <span class="o">=</span> <span class="s2">&#34;127.0.0.1&#34;</span>
</span></span><span class="line"><span class="cl"><span class="p">})</span>
</span></span></code></pre></div><p>What each part does:</p>
<ul>
<li><code>newServer</code>: the BIND resolver dnsdist forwards to.</li>
<li><code>addDOHLocal</code>: the DoH listener on 443, with certificate, key and URL path.</li>
<li><code>addTLSLocal</code>: a DoT listener on 853, sharing the same certificate.</li>
<li><code>addACL</code>: the networks allowed to query.</li>
<li><code>addAction(AllRule(), LogAction(...))</code>: log every query to a file.</li>
<li><code>webserver</code> / <code>setWebserverConfig</code>: monitoring interface on localhost only. Change the password.</li>
</ul>
<h3 id="start-dnsdist">Start dnsdist <a class="anchor" data-pagefind-ignore href="#start-dnsdist" aria-label="Link to this section">#</a></h3>
<p>Start the service and send a test query. The <code>dns=</code> value is a base64url-encoded query for <code>example.com</code> A.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">systemctl <span class="nb">enable</span> dnsdist
</span></span><span class="line"><span class="cl">systemctl start dnsdist
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test DoH</span>
</span></span><span class="line"><span class="cl">curl -H <span class="s1">&#39;accept: application/dns-message&#39;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;https://dns.example.com/dns-query?dns=AAABAAABAAAAAAAAB2V4YW1wbGUDY29tAAABAAE=&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    -o - <span class="p">|</span> xxd
</span></span></code></pre></div><h2 id="option-3-dedicated-doh-proxy-doh-server">Option 3: Dedicated DoH Proxy (doh-server) <a class="anchor" data-pagefind-ignore href="#option-3-dedicated-doh-proxy-doh-server" aria-label="Link to this section">#</a></h2>
<p>The <code>doh-server</code> from m13253/dns-over-https is a lightweight, purpose-built DoH proxy. It speaks plain HTTP on localhost; nginx in front handles TLS, access control and rate limiting.</p>
<p>The flow: client → nginx (443, TLS) → doh-server (127.0.0.1:8054, HTTP) → BIND (127.0.0.1:53, DNS).</p>
<h3 id="install-doh-server">Install doh-server <a class="anchor" data-pagefind-ignore href="#install-doh-server" aria-label="Link to this section">#</a></h3>
<p>The project does not publish prebuilt binaries on its GitHub releases, so build it with Go:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Build the latest release (v2.3.10 needs Go 1.23.5 or newer; an older go command,</span>
</span></span><span class="line"><span class="cl"><span class="c1"># such as Ubuntu 24.04&#39;s 1.22, downloads a newer toolchain itself with the default GOTOOLCHAIN=auto)</span>
</span></span><span class="line"><span class="cl"><span class="nv">GOBIN</span><span class="o">=</span>/usr/local/bin go install github.com/m13253/dns-over-https/v2/doh-server@latest
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create config directory</span>
</span></span><span class="line"><span class="cl">mkdir -p /etc/dns-over-https
</span></span></code></pre></div><h3 id="configure-doh-server">Configure doh-server <a class="anchor" data-pagefind-ignore href="#configure-doh-server" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml"><span class="line"><span class="cl"><span class="c"># /etc/dns-over-https/doh-server.conf</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nx">listen</span> <span class="p">=</span> <span class="p">[</span>
</span></span><span class="line"><span class="cl">    <span class="s2">&#34;127.0.0.1:8054&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="s2">&#34;[::1]:8054&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl"><span class="p">]</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nx">path</span> <span class="p">=</span> <span class="s2">&#34;/dns-query&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nx">upstream</span> <span class="p">=</span> <span class="p">[</span>
</span></span><span class="line"><span class="cl">    <span class="s2">&#34;udp:127.0.0.1:53&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl"><span class="p">]</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nx">timeout</span> <span class="p">=</span> <span class="mi">10</span>
</span></span><span class="line"><span class="cl"><span class="nx">tries</span> <span class="p">=</span> <span class="mi">3</span>
</span></span><span class="line"><span class="cl"><span class="nx">verbose</span> <span class="p">=</span> <span class="kc">false</span>
</span></span><span class="line"><span class="cl"><span class="nx">log_guessed_client_ip</span> <span class="p">=</span> <span class="kc">false</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c"># ECS (EDNS Client Subnet) handling</span>
</span></span><span class="line"><span class="cl"><span class="nx">ecs_allow_non_global_ip</span> <span class="p">=</span> <span class="kc">false</span>
</span></span><span class="line"><span class="cl"><span class="nx">ecs_use_precise_ip</span> <span class="p">=</span> <span class="kc">false</span>
</span></span></code></pre></div><ul>
<li><code>listen</code>: localhost only; nginx is the only client.</li>
<li><code>upstream</code>: the BIND resolver.</li>
<li><code>timeout</code> / <code>tries</code>: seconds per upstream query, and how many attempts.</li>
<li><code>ecs_*</code>: EDNS Client Subnet handling. No subnet is sent for private client addresses, and public ones are truncated instead of passed in full.</li>
</ul>
<p>doh-server&rsquo;s default port is 8053. This post uses 8054 instead, because the BIND statistics channel in the monitoring post of this series already listens on 127.0.0.1:8053.</p>
<h3 id="nginx-as-tls-terminator">nginx as TLS Terminator <a class="anchor" data-pagefind-ignore href="#nginx-as-tls-terminator" aria-label="Link to this section">#</a></h3>
<p>nginx accepts HTTPS on 443 and passes <code>/dns-query</code> to doh-server. Everything else returns 404.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-nginx" data-lang="nginx"><span class="line"><span class="cl"><span class="c1"># /etc/nginx/sites-available/doh
</span></span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">upstream</span> <span class="s">doh_backend</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="kn">server</span> <span class="n">127.0.0.1</span><span class="p">:</span><span class="mi">8054</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="kn">keepalive</span> <span class="mi">30</span><span class="p">;</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">server</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="kn">listen</span> <span class="mi">443</span> <span class="s">ssl</span> <span class="s">http2</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="kn">listen</span> <span class="s">[::]:443</span> <span class="s">ssl</span> <span class="s">http2</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="kn">server_name</span> <span class="s">dns.example.com</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># TLS configuration
</span></span></span><span class="line"><span class="cl">    <span class="kn">ssl_certificate</span> <span class="s">/etc/letsencrypt/live/dns.example.com/fullchain.pem</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="kn">ssl_certificate_key</span> <span class="s">/etc/letsencrypt/live/dns.example.com/privkey.pem</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="kn">ssl_protocols</span> <span class="s">TLSv1.2</span> <span class="s">TLSv1.3</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="kn">ssl_ciphers</span> <span class="s">ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="kn">ssl_prefer_server_ciphers</span> <span class="no">on</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="kn">ssl_session_cache</span> <span class="s">shared:SSL:10m</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="kn">ssl_session_timeout</span> <span class="s">1d</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="kn">ssl_session_tickets</span> <span class="no">off</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># HSTS
</span></span></span><span class="line"><span class="cl">    <span class="kn">add_header</span> <span class="s">Strict-Transport-Security</span> <span class="s">&#34;max-age=63072000&#34;</span> <span class="s">always</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># DoH endpoint
</span></span></span><span class="line"><span class="cl">    <span class="kn">location</span> <span class="s">/dns-query</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="kn">proxy_pass</span> <span class="s">http://doh_backend/dns-query</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">proxy_set_header</span> <span class="s">Host</span> <span class="nv">$host</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">proxy_set_header</span> <span class="s">X-Real-IP</span> <span class="nv">$remote_addr</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">proxy_set_header</span> <span class="s">X-Forwarded-For</span> <span class="nv">$proxy_add_x_forwarded_for</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">proxy_set_header</span> <span class="s">X-Forwarded-Proto</span> <span class="nv">$scheme</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="c1"># Important for DoH
</span></span></span><span class="line"><span class="cl">        <span class="kn">proxy_http_version</span> <span class="mi">1</span><span class="s">.1</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">proxy_set_header</span> <span class="s">Connection</span> <span class="s">&#34;&#34;</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="c1"># Timeouts
</span></span></span><span class="line"><span class="cl">        <span class="kn">proxy_connect_timeout</span> <span class="s">5s</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">proxy_read_timeout</span> <span class="s">30s</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">proxy_send_timeout</span> <span class="s">30s</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="c1"># Access control
</span></span></span><span class="line"><span class="cl">        <span class="kn">allow</span> <span class="n">192.168.0.0</span><span class="s">/16</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">allow</span> <span class="n">10.0.0.0</span><span class="s">/8</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">deny</span> <span class="s">all</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># Health check
</span></span></span><span class="line"><span class="cl">    <span class="kn">location</span> <span class="s">/health</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="kn">access_log</span> <span class="no">off</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">return</span> <span class="mi">200</span> <span class="s">&#34;healthy\n&#34;</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># Block everything else
</span></span></span><span class="line"><span class="cl">    <span class="kn">location</span> <span class="s">/</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="kn">return</span> <span class="mi">404</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span></code></pre></div><ul>
<li><code>keepalive 30</code> with <code>proxy_http_version 1.1</code> and an empty <code>Connection</code> header: reuse connections to doh-server instead of opening one per query.</li>
<li><code>allow</code> / <code>deny</code>: only your own networks may use the endpoint.</li>
<li><code>location /health</code>: a check for load balancers and monitoring.</li>
</ul>
<h3 id="systemd-service-for-doh-server">Systemd Service for doh-server <a class="anchor" data-pagefind-ignore href="#systemd-service-for-doh-server" aria-label="Link to this section">#</a></h3>
<p>Run doh-server as an unprivileged user, restart it on failure, and tie it to BIND with <code>Requires=named.service</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-ini" data-lang="ini"><span class="line"><span class="cl"><span class="c1"># /etc/systemd/system/doh-server.service</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">[Unit]</span>
</span></span><span class="line"><span class="cl"><span class="na">Description</span><span class="o">=</span><span class="s">DNS over HTTPS Server</span>
</span></span><span class="line"><span class="cl"><span class="na">After</span><span class="o">=</span><span class="s">network.target</span>
</span></span><span class="line"><span class="cl"><span class="na">Requires</span><span class="o">=</span><span class="s">named.service</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">[Service]</span>
</span></span><span class="line"><span class="cl"><span class="na">Type</span><span class="o">=</span><span class="s">simple</span>
</span></span><span class="line"><span class="cl"><span class="na">ExecStart</span><span class="o">=</span><span class="s">/usr/local/bin/doh-server -conf /etc/dns-over-https/doh-server.conf</span>
</span></span><span class="line"><span class="cl"><span class="na">Restart</span><span class="o">=</span><span class="s">always</span>
</span></span><span class="line"><span class="cl"><span class="na">RestartSec</span><span class="o">=</span><span class="s">5</span>
</span></span><span class="line"><span class="cl"><span class="na">User</span><span class="o">=</span><span class="s">nobody</span>
</span></span><span class="line"><span class="cl"><span class="na">Group</span><span class="o">=</span><span class="s">nogroup</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">[Install]</span>
</span></span><span class="line"><span class="cl"><span class="na">WantedBy</span><span class="o">=</span><span class="s">multi-user.target</span>
</span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">systemctl daemon-reload
</span></span><span class="line"><span class="cl">systemctl <span class="nb">enable</span> doh-server
</span></span><span class="line"><span class="cl">systemctl start doh-server
</span></span></code></pre></div><h2 id="testing-doh">Testing DoH <a class="anchor" data-pagefind-ignore href="#testing-doh" aria-label="Link to this section">#</a></h2>
<h3 id="using-curl">Using curl <a class="anchor" data-pagefind-ignore href="#using-curl" aria-label="Link to this section">#</a></h3>
<p>curl sends a raw wire-format query. The base64 string is the same <code>example.com</code> A query; <code>xxd</code> shows the binary answer.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># POST method (recommended)</span>
</span></span><span class="line"><span class="cl">curl -s -H <span class="s1">&#39;content-type: application/dns-message&#39;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    -H <span class="s1">&#39;accept: application/dns-message&#39;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    --data-binary @- <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s1">&#39;https://dns.example.com/dns-query&#39;</span> &lt; &lt;<span class="o">(</span><span class="nb">echo</span> -n <span class="s1">&#39;AAABAAABAAAAAAAAB2V4YW1wbGUDY29tAAABAAE=&#39;</span> <span class="p">|</span> base64 -d<span class="o">)</span> <span class="p">|</span> xxd
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># GET method with base64url encoded query</span>
</span></span><span class="line"><span class="cl"><span class="nv">DNS_QUERY</span><span class="o">=</span><span class="k">$(</span><span class="nb">echo</span> -n <span class="s1">&#39;AAABAAABAAAAAAAAB2V4YW1wbGUDY29tAAABAAE=&#39;</span> <span class="p">|</span> base64 -d <span class="p">|</span> base64 <span class="p">|</span> tr <span class="s1">&#39;+/&#39;</span> <span class="s1">&#39;-_&#39;</span> <span class="p">|</span> tr -d <span class="s1">&#39;=&#39;</span><span class="k">)</span>
</span></span><span class="line"><span class="cl">curl -s -H <span class="s1">&#39;accept: application/dns-message&#39;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;https://dns.example.com/dns-query?dns=</span><span class="nv">$DNS_QUERY</span><span class="s2">&#34;</span> <span class="p">|</span> xxd
</span></span></code></pre></div><h3 id="using-kdig">Using kdig <a class="anchor" data-pagefind-ignore href="#using-kdig" aria-label="Link to this section">#</a></h3>
<p><code>kdig</code> decodes the answer for you, which makes it easier to read than curl:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># kdig from knot-dnsutils supports DoH</span>
</span></span><span class="line"><span class="cl">kdig +https @dns.example.com example.com A
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># With custom path</span>
</span></span><span class="line"><span class="cl">kdig +https<span class="o">=</span>/dns-query @dns.example.com example.com A
</span></span></code></pre></div><h3 id="using-dog">Using dog <a class="anchor" data-pagefind-ignore href="#using-dog" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># dog is a modern DNS client</span>
</span></span><span class="line"><span class="cl">dog --https @https://dns.example.com/dns-query example.com A
</span></span></code></pre></div><h2 id="client-configuration">Client Configuration <a class="anchor" data-pagefind-ignore href="#client-configuration" aria-label="Link to this section">#</a></h2>
<h3 id="firefox">Firefox <a class="anchor" data-pagefind-ignore href="#firefox" aria-label="Link to this section">#</a></h3>
<ol>
<li>Open <code>about:config</code></li>
<li>Set <code>network.trr.mode</code> to <code>2</code> (prefer DoH) or <code>3</code> (DoH only)</li>
<li>Set <code>network.trr.uri</code> to <code>https://dns.example.com/dns-query</code></li>
<li>Optionally set <code>network.trr.bootstrapAddress</code> to your server&rsquo;s IP</li>
</ol>
<p>Mode <code>2</code> falls back to normal DNS when DoH fails; mode <code>3</code> does not.</p>
<h3 id="chromeedge">Chrome/Edge <a class="anchor" data-pagefind-ignore href="#chromeedge" aria-label="Link to this section">#</a></h3>
<ol>
<li>Settings -&gt; Privacy and Security -&gt; Security</li>
<li>Enable &ldquo;Use secure DNS&rdquo;</li>
<li>Select &ldquo;Custom&rdquo; and enter <code>https://dns.example.com/dns-query</code></li>
</ol>
<h3 id="systemd-resolved-linux">systemd-resolved (Linux) <a class="anchor" data-pagefind-ignore href="#systemd-resolved-linux" aria-label="Link to this section">#</a></h3>
<p>systemd-resolved uses DoT, not DoH:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-ini" data-lang="ini"><span class="line"><span class="cl"><span class="c1"># /etc/systemd/resolved.conf</span>
</span></span><span class="line"><span class="cl"><span class="k">[Resolve]</span>
</span></span><span class="line"><span class="cl"><span class="na">DNS</span><span class="o">=</span><span class="s">192.168.1.1#dns.example.com</span>
</span></span><span class="line"><span class="cl"><span class="na">DNSOverTLS</span><span class="o">=</span><span class="s">yes</span>
</span></span><span class="line"><span class="cl"><span class="c1"># Note: systemd-resolved uses DoT, not DoH directly</span>
</span></span></code></pre></div><p>For DoH on Linux, use a local DoH client like <code>dnscrypt-proxy</code>. It listens on 127.0.0.1:53 and forwards to your DoH server:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml"><span class="line"><span class="cl"><span class="c"># /etc/dnscrypt-proxy/dnscrypt-proxy.toml</span>
</span></span><span class="line"><span class="cl"><span class="nx">listen_addresses</span> <span class="p">=</span> <span class="p">[</span><span class="s1">&#39;127.0.0.1:53&#39;</span><span class="p">]</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="p">[</span><span class="nx">static</span><span class="p">]</span>
</span></span><span class="line"><span class="cl"><span class="p">[</span><span class="nx">static</span><span class="p">.</span><span class="s1">&#39;myresolver&#39;</span><span class="p">]</span>
</span></span><span class="line"><span class="cl"><span class="nx">stamp</span> <span class="p">=</span> <span class="s1">&#39;sdns://AgcAAAAAAAAADzE5Mi4xNjguMS4xOjQ0MwAPZG5zLmV4YW1wbGUuY29tCi9kbnMtcXVlcnk&#39;</span>
</span></span></code></pre></div><p>The stamp encodes address <code>192.168.1.1:443</code>, host <code>dns.example.com</code> and path <code>/dns-query</code>. Generate your own with the <a href="https://dnscrypt.info/stamps/" rel="noopener">DNS stamp calculator</a>.</p>
<h2 id="json-api-support">JSON API Support <a class="anchor" data-pagefind-ignore href="#json-api-support" aria-label="Link to this section">#</a></h2>
<p>Some clients prefer JSON format. This nginx snippet (Lua, as in Option 1) answers requests with <code>Accept: application/dns-json</code>. It reads <code>name</code> and <code>type</code> from the query string, resolves through BIND and returns a Google-style JSON response.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-nginx" data-lang="nginx"><span class="line"><span class="cl"><span class="k">location</span> <span class="s">/dns-query</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># Check Accept header for JSON
</span></span></span><span class="line"><span class="cl">    <span class="kn">set</span> <span class="nv">$dns_format</span> <span class="s">&#34;wire&#34;</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="kn">if</span> <span class="s">(</span><span class="nv">$http_accept</span> <span class="p">~</span><span class="sr">*</span> <span class="s">&#34;application/dns-json&#34;)</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="kn">set</span> <span class="nv">$dns_format</span> <span class="s">&#34;json&#34;</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># For JSON, use Google&#39;s format
</span></span></span><span class="line"><span class="cl">    <span class="kn">if</span> <span class="s">(</span><span class="nv">$dns_format</span> <span class="p">=</span> <span class="s">&#34;json&#34;)</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="c1"># Handle JSON queries
</span></span></span><span class="line"><span class="cl">        <span class="kn">content_by_lua_block</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">            <span class="kn">local</span> <span class="s">resolver</span> <span class="p">=</span> <span class="s">require</span> <span class="s">&#34;resty.dns.resolver&#34;</span>
</span></span><span class="line"><span class="cl">            <span class="s">local</span> <span class="s">cjson</span> <span class="p">=</span> <span class="s">require</span> <span class="s">&#34;cjson&#34;</span>
</span></span><span class="line"><span class="cl">            
</span></span><span class="line"><span class="cl">            <span class="s">local</span> <span class="s">name</span> <span class="p">=</span> <span class="s">ngx.var.arg_name</span>
</span></span><span class="line"><span class="cl">            <span class="s">local</span> <span class="s">qtype</span> <span class="p">=</span> <span class="s">ngx.var.arg_type</span> <span class="s">or</span> <span class="s">&#34;A&#34;</span>
</span></span><span class="line"><span class="cl">            
</span></span><span class="line"><span class="cl">            <span class="s">if</span> <span class="s">not</span> <span class="s">name</span> <span class="s">then</span>
</span></span><span class="line"><span class="cl">                <span class="s">ngx.status</span> <span class="p">=</span> <span class="mi">400</span>
</span></span><span class="line"><span class="cl">                <span class="s">ngx.say(cjson.encode(</span><span class="p">{</span><span class="kn">Status</span> <span class="p">=</span> <span class="mi">2</span><span class="s">,</span> <span class="s">Comment</span> <span class="p">=</span> <span class="s">&#34;Missing</span> <span class="s">name</span> <span class="s">parameter&#34;</span><span class="err">}</span><span class="s">))</span>
</span></span><span class="line"><span class="cl">                <span class="s">return</span>
</span></span><span class="line"><span class="cl">            <span class="s">end</span>
</span></span><span class="line"><span class="cl">            
</span></span><span class="line"><span class="cl">            <span class="s">local</span> <span class="s">r,</span> <span class="s">err</span> <span class="p">=</span> <span class="s">resolver:new</span><span class="p">{</span>
</span></span><span class="line"><span class="cl">                <span class="kn">nameservers</span> <span class="p">=</span> <span class="p">{</span><span class="kn">{&#34;127.0.0.1&#34;,</span> <span class="mi">53</span><span class="err">}}</span><span class="s">,</span>
</span></span><span class="line"><span class="cl">                <span class="s">timeout</span> <span class="p">=</span> <span class="mi">2000</span><span class="s">,</span>
</span></span><span class="line"><span class="cl">            <span class="err">}</span>
</span></span><span class="line"><span class="cl">            
</span></span><span class="line"><span class="cl">            <span class="s">if</span> <span class="s">not</span> <span class="s">r</span> <span class="s">then</span>
</span></span><span class="line"><span class="cl">                <span class="s">ngx.status</span> <span class="p">=</span> <span class="mi">500</span>
</span></span><span class="line"><span class="cl">                <span class="s">ngx.say(cjson.encode(</span><span class="p">{</span><span class="kn">Status</span> <span class="p">=</span> <span class="mi">2</span><span class="s">,</span> <span class="s">Comment</span> <span class="p">=</span> <span class="s">err</span><span class="err">}</span><span class="s">))</span>
</span></span><span class="line"><span class="cl">                <span class="s">return</span>
</span></span><span class="line"><span class="cl">            <span class="s">end</span>
</span></span><span class="line"><span class="cl">            
</span></span><span class="line"><span class="cl">            <span class="s">local</span> <span class="s">answers,</span> <span class="s">err</span> <span class="p">=</span> <span class="s">r:query(name,</span> <span class="p">{</span><span class="kn">qtype</span> <span class="p">=</span> <span class="s">resolver[&#34;TYPE_&#34;</span> <span class="s">..</span> <span class="s">qtype]</span><span class="err">}</span><span class="s">)</span>
</span></span><span class="line"><span class="cl">            
</span></span><span class="line"><span class="cl">            <span class="s">if</span> <span class="s">not</span> <span class="s">answers</span> <span class="s">then</span>
</span></span><span class="line"><span class="cl">                <span class="s">ngx.status</span> <span class="p">=</span> <span class="mi">500</span>
</span></span><span class="line"><span class="cl">                <span class="s">ngx.say(cjson.encode(</span><span class="p">{</span><span class="kn">Status</span> <span class="p">=</span> <span class="mi">2</span><span class="s">,</span> <span class="s">Comment</span> <span class="p">=</span> <span class="s">err</span><span class="err">}</span><span class="s">))</span>
</span></span><span class="line"><span class="cl">                <span class="s">return</span>
</span></span><span class="line"><span class="cl">            <span class="s">end</span>
</span></span><span class="line"><span class="cl">            
</span></span><span class="line"><span class="cl">            <span class="s">--</span> <span class="s">Format</span> <span class="s">response</span>
</span></span><span class="line"><span class="cl">            <span class="s">local</span> <span class="s">response</span> <span class="p">=</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">                <span class="kn">Status</span> <span class="p">=</span> <span class="mi">0</span><span class="s">,</span>
</span></span><span class="line"><span class="cl">                <span class="s">TC</span> <span class="p">=</span> <span class="s">false,</span>
</span></span><span class="line"><span class="cl">                <span class="s">RD</span> <span class="p">=</span> <span class="s">true,</span>
</span></span><span class="line"><span class="cl">                <span class="s">RA</span> <span class="p">=</span> <span class="s">true,</span>
</span></span><span class="line"><span class="cl">                <span class="s">AD</span> <span class="p">=</span> <span class="s">false,</span>
</span></span><span class="line"><span class="cl">                <span class="s">CD</span> <span class="p">=</span> <span class="s">false,</span>
</span></span><span class="line"><span class="cl">                <span class="s">Question</span> <span class="p">=</span> <span class="p">{</span><span class="kn">{name</span> <span class="p">=</span> <span class="s">name,</span> <span class="s">type</span> <span class="p">=</span> <span class="s">qtype</span><span class="err">}}</span><span class="s">,</span>
</span></span><span class="line"><span class="cl">                <span class="s">Answer</span> <span class="p">=</span> <span class="p">{}</span>
</span></span><span class="line"><span class="cl">            <span class="p">}</span>
</span></span><span class="line"><span class="cl">            
</span></span><span class="line"><span class="cl">            <span class="kn">for</span> <span class="s">i,</span> <span class="s">ans</span> <span class="s">in</span> <span class="s">ipairs(answers)</span> <span class="s">do</span>
</span></span><span class="line"><span class="cl">                <span class="s">table.insert(response.Answer,</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">                    <span class="kn">name</span> <span class="p">=</span> <span class="s">ans.name,</span>
</span></span><span class="line"><span class="cl">                    <span class="s">type</span> <span class="p">=</span> <span class="s">ans.type,</span>
</span></span><span class="line"><span class="cl">                    <span class="s">TTL</span> <span class="p">=</span> <span class="s">ans.ttl,</span>
</span></span><span class="line"><span class="cl">                    <span class="s">data</span> <span class="p">=</span> <span class="s">ans.address</span> <span class="s">or</span> <span class="s">ans.cname</span> <span class="s">or</span> <span class="s">ans.exchange</span> <span class="s">or</span> <span class="s">ans.txt</span>
</span></span><span class="line"><span class="cl">                <span class="err">}</span><span class="s">)</span>
</span></span><span class="line"><span class="cl">            <span class="s">end</span>
</span></span><span class="line"><span class="cl">            
</span></span><span class="line"><span class="cl">            <span class="s">ngx.header[&#34;Content-Type&#34;]</span> <span class="p">=</span> <span class="s">&#34;application/dns-json&#34;</span>
</span></span><span class="line"><span class="cl">            <span class="s">ngx.say(cjson.encode(response))</span>
</span></span><span class="line"><span class="cl">        <span class="err">}</span>
</span></span><span class="line"><span class="cl">    <span class="err">}</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># Wire format handling...
</span></span></span><span class="line"><span class="cl"><span class="err">}</span>
</span></span></code></pre></div><h2 id="performance-optimization">Performance Optimization <a class="anchor" data-pagefind-ignore href="#performance-optimization" aria-label="Link to this section">#</a></h2>
<h3 id="http2-configuration">HTTP/2 Configuration <a class="anchor" data-pagefind-ignore href="#http2-configuration" aria-label="Link to this section">#</a></h3>
<p>Browsers keep one HTTP/2 connection open and send many queries over it. Long keepalive values avoid new TLS handshakes:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-nginx" data-lang="nginx"><span class="line"><span class="cl"><span class="k">http</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># Connection keepalive (HTTP/2 itself is enabled on the listen directive)
</span></span></span><span class="line"><span class="cl">    <span class="kn">keepalive_timeout</span> <span class="s">300s</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="kn">keepalive_requests</span> <span class="mi">10000</span><span class="p">;</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span></code></pre></div><ul>
<li><code>keepalive_timeout 300s</code>: keep idle client connections open for 5 minutes.</li>
<li><code>keepalive_requests 10000</code>: requests allowed per connection before nginx closes it.</li>
</ul>
<h3 id="caching-doh-responses">Caching DoH Responses <a class="anchor" data-pagefind-ignore href="#caching-doh-responses" aria-label="Link to this section">#</a></h3>
<p>nginx can cache answers so repeated queries do not reach doh-server and BIND. The cache key includes the POST body and the GET <code>dns</code> parameter, so each distinct query is cached separately.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-nginx" data-lang="nginx"><span class="line"><span class="cl"><span class="k">proxy_cache_path</span> <span class="s">/var/cache/nginx/doh</span> 
</span></span><span class="line"><span class="cl">    <span class="s">levels=1:2</span> 
</span></span><span class="line"><span class="cl">    <span class="s">keys_zone=doh_cache:10m</span> 
</span></span><span class="line"><span class="cl">    <span class="s">max_size=100m</span> 
</span></span><span class="line"><span class="cl">    <span class="s">inactive=5m</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">server</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="kn">location</span> <span class="s">/dns-query</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="kn">proxy_cache</span> <span class="s">doh_cache</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">proxy_cache_valid</span> <span class="mi">200</span> <span class="s">300s</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">proxy_cache_key</span> <span class="nv">$request_body$arg_dns</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">proxy_cache_methods</span> <span class="s">GET</span> <span class="s">POST</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="c1"># doh-server sends &#34;Cache-Control: private&#34;, which nginx never caches;
</span></span></span><span class="line"><span class="cl">        <span class="c1"># ignore it so the Expires header (based on the DNS TTL) is used
</span></span></span><span class="line"><span class="cl">        <span class="kn">proxy_ignore_headers</span> <span class="s">Cache-Control</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="c1"># Add cache status header
</span></span></span><span class="line"><span class="cl">        <span class="kn">add_header</span> <span class="s">X-Cache-Status</span> <span class="nv">$upstream_cache_status</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span></code></pre></div><ul>
<li><code>proxy_cache_methods GET POST</code>: nginx normally only caches GET and HEAD.</li>
<li><code>X-Cache-Status</code>: shows <code>HIT</code> or <code>MISS</code>, useful when testing.</li>
</ul>
<h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<h3 id="rate-limiting">Rate Limiting <a class="anchor" data-pagefind-ignore href="#rate-limiting" aria-label="Link to this section">#</a></h3>
<p>Limit each client address, so one client cannot flood the resolver:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-nginx" data-lang="nginx"><span class="line"><span class="cl"><span class="c1"># Define rate limit zone
</span></span></span><span class="line"><span class="cl"><span class="k">limit_req_zone</span> <span class="nv">$binary_remote_addr</span> <span class="s">zone=doh_limit:10m</span> <span class="s">rate=50r/s</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">server</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="kn">location</span> <span class="s">/dns-query</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="kn">limit_req</span> <span class="s">zone=doh_limit</span> <span class="s">burst=100</span> <span class="s">nodelay</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">limit_req_status</span> <span class="mi">429</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span></code></pre></div><ul>
<li><code>rate=50r/s</code>: 50 requests per second per client address.</li>
<li><code>burst=100 nodelay</code>: allow short bursts above that without delaying them.</li>
<li><code>limit_req_status 429</code>: answer &ldquo;Too Many Requests&rdquo; instead of the default 503.</li>
</ul>
<h3 id="access-control">Access Control <a class="anchor" data-pagefind-ignore href="#access-control" aria-label="Link to this section">#</a></h3>
<p>An open DoH resolver can be abused by anyone on the internet. Restrict it to your own networks:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-nginx" data-lang="nginx"><span class="line"><span class="cl"><span class="k">server</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="kn">location</span> <span class="s">/dns-query</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="c1"># Allow private networks
</span></span></span><span class="line"><span class="cl">        <span class="kn">allow</span> <span class="n">10.0.0.0</span><span class="s">/8</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">allow</span> <span class="n">172.16.0.0</span><span class="s">/12</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">allow</span> <span class="n">192.168.0.0</span><span class="s">/16</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="c1"># Block everyone else
</span></span></span><span class="line"><span class="cl">        <span class="kn">deny</span> <span class="s">all</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="c1"># Or use GeoIP
</span></span></span><span class="line"><span class="cl">        <span class="c1"># if ($geoip_country_code != &#34;US&#34;) {
</span></span></span><span class="line"><span class="cl">        <span class="c1">#     return 403;
</span></span></span><span class="line"><span class="cl">        <span class="c1"># }
</span></span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span></code></pre></div><h3 id="request-validation">Request Validation <a class="anchor" data-pagefind-ignore href="#request-validation" aria-label="Link to this section">#</a></h3>
<p>Reject anything that is not a valid DoH request before it reaches doh-server:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-nginx" data-lang="nginx"><span class="line"><span class="cl"><span class="c1"># GET requests carry the query in ?dns= and have no Content-Type,
</span></span></span><span class="line"><span class="cl"><span class="c1"># so only check the Content-Type of POST requests (map goes in the http block)
</span></span></span><span class="line"><span class="cl"><span class="k">map</span> <span class="s">&#34;</span><span class="nv">$request_method:$http_content_type&#34;</span> <span class="nv">$doh_bad_request</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="kn">default</span>                          <span class="mi">1</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="kn">&#34;~^GET:&#34;</span>                         <span class="mi">0</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="kn">&#34;~^POST:application/dns-message&#34;</span> <span class="mi">0</span><span class="p">;</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">server</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="kn">location</span> <span class="s">/dns-query</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="c1"># Only allow proper content types
</span></span></span><span class="line"><span class="cl">        <span class="kn">if</span> <span class="s">(</span><span class="nv">$doh_bad_request</span><span class="s">)</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">            <span class="kn">return</span> <span class="mi">415</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="p">}</span>
</span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="c1"># Limit request body size
</span></span></span><span class="line"><span class="cl">        <span class="kn">client_max_body_size</span> <span class="mi">512</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span></code></pre></div><ul>
<li><code>$doh_bad_request</code>: 0 for GET and for POST with <code>application/dns-message</code>; 1 for everything else, answered with 415 (Unsupported Media Type).</li>
<li><code>client_max_body_size 512</code>: DNS queries are small; bigger bodies are rejected.</li>
</ul>
<h2 id="complete-production-configuration">Complete Production Configuration <a class="anchor" data-pagefind-ignore href="#complete-production-configuration" aria-label="Link to this section">#</a></h2>
<p>This combines Option 3 with the hardening above into one <code>nginx.conf</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-nginx" data-lang="nginx"><span class="line"><span class="cl"><span class="c1"># /etc/nginx/nginx.conf
</span></span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">user</span> <span class="s">www-data</span><span class="p">;</span>
</span></span><span class="line"><span class="cl"><span class="k">worker_processes</span> <span class="s">auto</span><span class="p">;</span>
</span></span><span class="line"><span class="cl"><span class="k">pid</span> <span class="s">/run/nginx.pid</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">events</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="kn">worker_connections</span> <span class="mi">4096</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="kn">use</span> <span class="s">epoll</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="kn">multi_accept</span> <span class="no">on</span><span class="p">;</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">http</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># Basic settings
</span></span></span><span class="line"><span class="cl">    <span class="kn">sendfile</span> <span class="no">on</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="kn">tcp_nopush</span> <span class="no">on</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="kn">tcp_nodelay</span> <span class="no">on</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="kn">types_hash_max_size</span> <span class="mi">2048</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="kn">server_tokens</span> <span class="no">off</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># Rate limiting
</span></span></span><span class="line"><span class="cl">    <span class="kn">limit_req_zone</span> <span class="nv">$binary_remote_addr</span> <span class="s">zone=doh_limit:10m</span> <span class="s">rate=100r/s</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="kn">limit_conn_zone</span> <span class="nv">$binary_remote_addr</span> <span class="s">zone=doh_conn:10m</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># Request validation: GET carries the query in ?dns=, POST must be application/dns-message
</span></span></span><span class="line"><span class="cl">    <span class="kn">map</span> <span class="s">&#34;</span><span class="nv">$request_method:$http_content_type&#34;</span> <span class="nv">$doh_bad_request</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="kn">default</span>                          <span class="mi">1</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">&#34;~^GET:&#34;</span>                         <span class="mi">0</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">&#34;~^POST:application/dns-message&#34;</span> <span class="mi">0</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># Logging
</span></span></span><span class="line"><span class="cl">    <span class="kn">log_format</span> <span class="s">doh</span> <span class="s">&#39;</span><span class="nv">$remote_addr</span> <span class="s">-</span> <span class="s">[</span><span class="nv">$time_local]</span> <span class="s">&#39;</span>
</span></span><span class="line"><span class="cl">                   <span class="s">&#39;&#34;</span><span class="nv">$request&#34;</span> <span class="nv">$status</span> <span class="nv">$body_bytes_sent</span> <span class="s">&#39;</span>
</span></span><span class="line"><span class="cl">                   <span class="s">&#39;&#34;</span><span class="nv">$http_user_agent&#34;</span> <span class="s">rt=</span><span class="nv">$request_time&#39;</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="kn">access_log</span> <span class="s">/var/log/nginx/doh-access.log</span> <span class="s">doh</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="kn">error_log</span> <span class="s">/var/log/nginx/doh-error.log</span> <span class="s">warn</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># DoH upstream
</span></span></span><span class="line"><span class="cl">    <span class="kn">upstream</span> <span class="s">doh_backend</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="kn">server</span> <span class="n">127.0.0.1</span><span class="p">:</span><span class="mi">8054</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">keepalive</span> <span class="mi">100</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># Redirect HTTP to HTTPS
</span></span></span><span class="line"><span class="cl">    <span class="kn">server</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="kn">listen</span> <span class="mi">80</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">server_name</span> <span class="s">dns.example.com</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">return</span> <span class="mi">301</span> <span class="s">https://</span><span class="nv">$host$request_uri</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># DoH server
</span></span></span><span class="line"><span class="cl">    <span class="kn">server</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="kn">listen</span> <span class="mi">443</span> <span class="s">ssl</span> <span class="s">http2</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">listen</span> <span class="s">[::]:443</span> <span class="s">ssl</span> <span class="s">http2</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">server_name</span> <span class="s">dns.example.com</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="c1"># TLS
</span></span></span><span class="line"><span class="cl">        <span class="kn">ssl_certificate</span> <span class="s">/etc/letsencrypt/live/dns.example.com/fullchain.pem</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">ssl_certificate_key</span> <span class="s">/etc/letsencrypt/live/dns.example.com/privkey.pem</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">ssl_protocols</span> <span class="s">TLSv1.2</span> <span class="s">TLSv1.3</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">ssl_ciphers</span> <span class="s">ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">ssl_prefer_server_ciphers</span> <span class="no">off</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">ssl_session_cache</span> <span class="s">shared:SSL:10m</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">ssl_session_timeout</span> <span class="s">1d</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">ssl_session_tickets</span> <span class="no">off</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="c1"># No OCSP stapling: Let&#39;s Encrypt certificates no longer carry an OCSP URL
</span></span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="c1"># Security headers
</span></span></span><span class="line"><span class="cl">        <span class="kn">add_header</span> <span class="s">Strict-Transport-Security</span> <span class="s">&#34;max-age=63072000&#34;</span> <span class="s">always</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">add_header</span> <span class="s">X-Content-Type-Options</span> <span class="s">nosniff</span> <span class="s">always</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="kn">add_header</span> <span class="s">X-Frame-Options</span> <span class="s">DENY</span> <span class="s">always</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="c1"># DoH endpoint
</span></span></span><span class="line"><span class="cl">        <span class="kn">location</span> <span class="s">/dns-query</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">            <span class="c1"># Rate limiting
</span></span></span><span class="line"><span class="cl">            <span class="kn">limit_req</span> <span class="s">zone=doh_limit</span> <span class="s">burst=200</span> <span class="s">nodelay</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">            <span class="kn">limit_conn</span> <span class="s">doh_conn</span> <span class="mi">50</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">            
</span></span><span class="line"><span class="cl">            <span class="c1"># Access control
</span></span></span><span class="line"><span class="cl">            <span class="kn">allow</span> <span class="n">192.168.0.0</span><span class="s">/16</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">            <span class="kn">allow</span> <span class="n">10.0.0.0</span><span class="s">/8</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">            <span class="kn">deny</span> <span class="s">all</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">            
</span></span><span class="line"><span class="cl">            <span class="c1"># Only allow proper content types
</span></span></span><span class="line"><span class="cl">            <span class="kn">if</span> <span class="s">(</span><span class="nv">$doh_bad_request</span><span class="s">)</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">                <span class="kn">return</span> <span class="mi">415</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">            <span class="p">}</span>
</span></span><span class="line"><span class="cl">            
</span></span><span class="line"><span class="cl">            <span class="c1"># Limit request body size
</span></span></span><span class="line"><span class="cl">            <span class="kn">client_max_body_size</span> <span class="mi">512</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">            
</span></span><span class="line"><span class="cl">            <span class="c1"># Proxy to doh-server
</span></span></span><span class="line"><span class="cl">            <span class="kn">proxy_pass</span> <span class="s">http://doh_backend</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">            <span class="kn">proxy_http_version</span> <span class="mi">1</span><span class="s">.1</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">            <span class="kn">proxy_set_header</span> <span class="s">Connection</span> <span class="s">&#34;&#34;</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">            <span class="kn">proxy_set_header</span> <span class="s">Host</span> <span class="nv">$host</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">            <span class="kn">proxy_set_header</span> <span class="s">X-Real-IP</span> <span class="nv">$remote_addr</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">            
</span></span><span class="line"><span class="cl">            <span class="c1"># Timeouts
</span></span></span><span class="line"><span class="cl">            <span class="kn">proxy_connect_timeout</span> <span class="s">5s</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">            <span class="kn">proxy_read_timeout</span> <span class="s">30s</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">            <span class="kn">proxy_send_timeout</span> <span class="s">30s</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="p">}</span>
</span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="kn">location</span> <span class="s">/health</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">            <span class="kn">access_log</span> <span class="no">off</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">            <span class="kn">return</span> <span class="mi">200</span> <span class="s">&#34;OK\n&#34;</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="p">}</span>
</span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="kn">location</span> <span class="s">/</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">            <span class="kn">return</span> <span class="mi">404</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">        <span class="p">}</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span></code></pre></div><p>Compared to the earlier snippets:</p>
<ul>
<li><code>limit_conn doh_conn 50</code>: at most 50 open connections per client address, on top of the request rate limit.</li>
<li><code>server_tokens off</code>: hide the nginx version.</li>
<li>The port 80 server only redirects to HTTPS.</li>
<li>A dedicated <code>doh</code> log format records the request time (<code>rt=</code>), useful to spot a slow backend.</li>
</ul>
<h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Likely cause</th>
					<th>Check</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>502 Bad Gateway</td>
					<td>doh-server not running or wrong port</td>
					<td><code>systemctl status doh-server</code>, <code>ss -tlnp</code></td>
			</tr>
			<tr>
					<td>TLS errors in clients</td>
					<td>Incomplete certificate chain or wrong name</td>
					<td><code>openssl s_client</code></td>
			</tr>
			<tr>
					<td>Queries time out or return SERVFAIL</td>
					<td>BIND not answering on localhost</td>
					<td><code>dig @127.0.0.1</code></td>
			</tr>
			<tr>
					<td>403</td>
					<td>Client address not in the <code>allow</code> list</td>
					<td>nginx access control</td>
			</tr>
			<tr>
					<td>415</td>
					<td>Wrong or missing Content-Type on POST</td>
					<td>Request validation map</td>
			</tr>
	</tbody>
</table>
<h3 id="check-doh-service">Check DoH Service <a class="anchor" data-pagefind-ignore href="#check-doh-service" aria-label="Link to this section">#</a></h3>
<p>Test each hop separately: doh-server directly, then through nginx, then with a real query:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Test backend directly</span>
</span></span><span class="line"><span class="cl">curl -v http://127.0.0.1:8054/dns-query
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test through nginx</span>
</span></span><span class="line"><span class="cl">curl -v https://dns.example.com/dns-query
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Debug DNS query</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> -ne <span class="s1">&#39;\x00\x00\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00\x07example\x03com\x00\x00\x01\x00\x01&#39;</span> <span class="p">|</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    curl -s -X POST -H <span class="s1">&#39;content-type: application/dns-message&#39;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    --data-binary @- https://dns.example.com/dns-query <span class="p">|</span> xxd
</span></span></code></pre></div><h3 id="common-issues">Common Issues <a class="anchor" data-pagefind-ignore href="#common-issues" aria-label="Link to this section">#</a></h3>
<p><strong>502 Bad Gateway:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check if doh-server is running</span>
</span></span><span class="line"><span class="cl">systemctl status doh-server
</span></span><span class="line"><span class="cl">ss -tlnp <span class="p">|</span> grep <span class="m">8054</span>
</span></span></code></pre></div><p><strong>SSL errors:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Verify certificate chain</span>
</span></span><span class="line"><span class="cl">openssl s_client -connect dns.example.com:443 -servername dns.example.com
</span></span></code></pre></div><p><strong>DNS resolution failures:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check BIND is responding</span>
</span></span><span class="line"><span class="cl">dig @127.0.0.1 example.com A
</span></span></code></pre></div><h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub: <a href="https://github.com/pderuiter/blog-bind-doh" rel="noopener">pderuiter/blog-bind-doh</a>. It creates an Ubuntu 24.04 VM on Proxmox and runs one playbook that sets up the localhost BIND resolver, builds doh-server on port 8054 and configures nginx with the complete production configuration above; <code>tests/verify.yml</code> then runs the curl and kdig checks from this post.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>BIND can serve DoH natively for simple setups. Combining it with nginx and doh-server (or dnsdist) gives a DoH service with rate limiting, access control and caching, under your own control.</p>
<p>Key takeaways:</p>
<ul>
<li>Use dnsdist for the simplest setup with both DoH and DoT</li>
<li>Use doh-server + nginx for maximum flexibility</li>
<li>Implement rate limiting and access controls</li>
<li>Enable HTTP/2 for best performance</li>
<li>Test with multiple clients (browsers, curl, kdig)</li>
</ul>
<p>The next post will cover integrating Kubernetes External-DNS with BIND for automatic DNS management, and the final post in this series covers monitoring your DNS infrastructure with Prometheus and Grafana.</p>
]]></content:encoded></item><item><title>Integrating Kubernetes External-DNS with BIND for Automatic DNS Management</title><link>https://blog.bsdserver.nl/integrating-kubernetes-external-dns-with-bind-for-automatic-dns-management/</link><guid isPermaLink="false">693b6cfc79eb54000160a575</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:16:44 +0000</pubDate><description>External-DNS is a Kubernetes controller that automatically creates and manages DNS records based on Kubernetes resources like Services and Ingresses.</description><category>BIND</category><category>DNS</category><category>Kubernetes</category><category>ExternalDNS</category><category>Automation</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/bind-k8s-external-dns.png" medium="image"/><content:encoded><![CDATA[<p>External-DNS is a Kubernetes controller that automatically creates and manages DNS records based on Kubernetes resources like Services and Ingresses. Without it, every new service means a manual DNS change, and deleted services leave stale records behind.</p>
<p>When combined with BIND using the RFC2136 (dynamic DNS) provider, you get fully automated DNS management for your Kubernetes workloads without relying on cloud DNS providers. This post sets up the BIND side, deploys External-DNS, and shows how Services, Ingresses and HTTPRoutes become DNS records.</p>
<h2 id="why-external-dns-with-bind">Why External-DNS with BIND? <a class="anchor" data-pagefind-ignore href="#why-external-dns-with-bind" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>No manual DNS changes</strong>: a hostname annotation or Ingress host is enough.</li>
<li><strong>Cleanup included</strong>: records disappear when the resource is deleted.</li>
<li><strong>Your own DNS</strong>: no cloud DNS provider needed; BIND stays the authority.</li>
<li><strong>Safe sharing</strong>: TXT ownership records keep External-DNS away from records it did not create.</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> for on-premises or homelab clusters with BIND as the authoritative DNS, where services come and go.</li>
<li><strong>Skip it</strong> when your zone is hosted at a cloud DNS provider (use External-DNS&rsquo;s provider for that instead), or for a handful of services that never change.</li>
</ul>
<h2 id="how-external-dns-works">How External-DNS Works <a class="anchor" data-pagefind-ignore href="#how-external-dns-works" aria-label="Link to this section">#</a></h2>
<p>External-DNS watches Kubernetes resources (Services, Ingresses, Gateway API resources) and synchronizes DNS records with an external DNS provider. For BIND, it uses the RFC2136 protocol - the same dynamic DNS update mechanism we covered in <a href="https://blog.bsdserver.nl/setting-up-dynamic-dns-updates-with-bind-and-tsig-authentication/">the previous post</a>.</p>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>External-DNS</td>
					<td>Kubernetes, one pod</td>
					<td>Watches resources, computes the records they need, sends signed updates.</td>
			</tr>
			<tr>
					<td>TSIG secret</td>
					<td>Kubernetes Secret</td>
					<td>The key External-DNS signs updates with.</td>
			</tr>
			<tr>
					<td>BIND zone (<code>type primary</code>)</td>
					<td>DNS server</td>
					<td>Accepts updates signed with <code>external-dns-key</code>, within its <code>update-policy</code>.</td>
			</tr>
			<tr>
					<td>TXT registry</td>
					<td>In the zone itself</td>
					<td>Marks which records belong to which External-DNS instance.</td>
			</tr>
	</tbody>
</table>
<p>The workflow:</p>
<ol>
<li>You deploy a Service or Ingress with DNS annotations</li>
<li>External-DNS detects the resource and its annotations</li>
<li>External-DNS sends DNS UPDATE requests to your BIND server</li>
<li>BIND creates or updates the DNS records</li>
<li>When resources are deleted, External-DNS removes the corresponding records</li>
</ol>
<h2 id="prerequisites">Prerequisites <a class="anchor" data-pagefind-ignore href="#prerequisites" aria-label="Link to this section">#</a></h2>
<h3 id="bind-configuration">BIND Configuration <a class="anchor" data-pagefind-ignore href="#bind-configuration" aria-label="Link to this section">#</a></h3>
<p>Your BIND server needs to accept dynamic updates. A dedicated key means External-DNS can only touch the zones you grant it. Generate a TSIG key for External-DNS:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">tsig-keygen -a hmac-sha256 external-dns-key &gt; /etc/named/keys/external-dns.key
</span></span></code></pre></div><p>Configure BIND to accept updates. <code>zonesub ANY</code> lets the key change any record in <code>k8s.example.com</code>; the reverse zone only allows PTR records:</p>
<pre tabindex="0"><code>// /etc/named.conf

include &#34;/etc/named/keys/external-dns.key&#34;;

zone &#34;k8s.example.com&#34; {
    type primary;
    file &#34;/var/named/dynamic/k8s.example.com.zone&#34;;
    update-policy {
        grant external-dns-key zonesub ANY;
    };
};

// If managing reverse DNS (External-DNS v0.14 doesn&#39;t create PTR records
// for RFC2136; newer releases have --create-ptr)
zone &#34;1.168.192.in-addr.arpa&#34; {
    type primary;
    file &#34;/var/named/dynamic/192.168.1.rev&#34;;
    update-policy {
        grant external-dns-key zonesub PTR;
    };
};
</code></pre><p>Create the initial zone file. It only needs the SOA and NS records; External-DNS adds the rest. The low TTLs (300) let changes reach clients quickly.</p>
<pre tabindex="0"><code>; /var/named/dynamic/k8s.example.com.zone
$TTL 300
@   IN  SOA ns1.example.com. admin.example.com. (
        2024010101  ; Serial
        3600        ; Refresh
        1800        ; Retry
        604800      ; Expire
        300 )       ; Minimum TTL

    IN  NS  ns1.example.com.
</code></pre><h2 id="deploying-external-dns">Deploying External-DNS <a class="anchor" data-pagefind-ignore href="#deploying-external-dns" aria-label="Link to this section">#</a></h2>
<p>Three pieces: a Secret with the TSIG key, RBAC so External-DNS can read cluster resources, and the Deployment itself.</p>
<h3 id="create-tsig-secret">Create TSIG Secret <a class="anchor" data-pagefind-ignore href="#create-tsig-secret" aria-label="Link to this section">#</a></h3>
<p>First, create a Kubernetes secret containing the TSIG key. Only the secret string goes in; the key name and algorithm are passed as flags.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Extract the secret from the key file</span>
</span></span><span class="line"><span class="cl"><span class="nv">TSIG_SECRET</span><span class="o">=</span><span class="k">$(</span>grep secret /etc/named/keys/external-dns.key <span class="p">|</span> cut -d <span class="s1">&#39;&#34;&#39;</span> -f2<span class="k">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">kubectl create namespace external-dns
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">kubectl create secret generic external-dns-tsig <span class="se">\
</span></span></span><span class="line"><span class="cl">  --namespace external-dns <span class="se">\
</span></span></span><span class="line"><span class="cl">  --from-literal<span class="o">=</span>tsig-secret<span class="o">=</span><span class="s2">&#34;</span><span class="nv">$TSIG_SECRET</span><span class="s2">&#34;</span>
</span></span></code></pre></div><p>Or as a YAML manifest:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">apiVersion</span><span class="p">:</span><span class="w"> </span><span class="l">v1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l">Secret</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">external-dns-tsig</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">namespace</span><span class="p">:</span><span class="w"> </span><span class="l">external-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">type</span><span class="p">:</span><span class="w"> </span><span class="l">Opaque</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">stringData</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">tsig-secret</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;your-base64-tsig-secret-here&#34;</span><span class="w">
</span></span></span></code></pre></div><h3 id="rbac-configuration">RBAC Configuration <a class="anchor" data-pagefind-ignore href="#rbac-configuration" aria-label="Link to this section">#</a></h3>
<p>External-DNS only reads from the Kubernetes API. The ClusterRole grants read access to the resources it can use as sources (Services, Ingresses, Gateway API routes), plus nodes, pods and namespaces it needs to resolve targets and filters.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">apiVersion</span><span class="p">:</span><span class="w"> </span><span class="l">v1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l">ServiceAccount</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">external-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">namespace</span><span class="p">:</span><span class="w"> </span><span class="l">external-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nn">---</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">apiVersion</span><span class="p">:</span><span class="w"> </span><span class="l">rbac.authorization.k8s.io/v1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l">ClusterRole</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">external-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">rules</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">apiGroups</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">resources</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;services&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;endpoints&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;pods&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">verbs</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;get&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;watch&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;list&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">apiGroups</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;extensions&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;networking.k8s.io&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">resources</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;ingresses&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">verbs</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;get&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;watch&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;list&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">apiGroups</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">resources</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;nodes&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">verbs</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;list&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;watch&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">apiGroups</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">resources</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;namespaces&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">verbs</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;get&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;watch&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;list&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">apiGroups</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;gateway.networking.k8s.io&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">resources</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;gateways&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;httproutes&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;tlsroutes&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;tcproutes&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;udproutes&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">verbs</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;get&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;watch&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;list&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nn">---</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">apiVersion</span><span class="p">:</span><span class="w"> </span><span class="l">rbac.authorization.k8s.io/v1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l">ClusterRoleBinding</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">external-dns-viewer</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">roleRef</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">apiGroup</span><span class="p">:</span><span class="w"> </span><span class="l">rbac.authorization.k8s.io</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l">ClusterRole</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">external-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">subjects</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l">ServiceAccount</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">external-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">namespace</span><span class="p">:</span><span class="w"> </span><span class="l">external-dns</span><span class="w">
</span></span></span></code></pre></div><h3 id="external-dns-deployment">External-DNS Deployment <a class="anchor" data-pagefind-ignore href="#external-dns-deployment" aria-label="Link to this section">#</a></h3>
<p>One replica with the <code>Recreate</code> strategy, so two External-DNS pods never update the zone at the same time. The flags are explained in the next section.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">apiVersion</span><span class="p">:</span><span class="w"> </span><span class="l">apps/v1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l">Deployment</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">external-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">namespace</span><span class="p">:</span><span class="w"> </span><span class="l">external-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">spec</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">replicas</span><span class="p">:</span><span class="w"> </span><span class="m">1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">strategy</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">type</span><span class="p">:</span><span class="w"> </span><span class="l">Recreate</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">selector</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">matchLabels</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">app</span><span class="p">:</span><span class="w"> </span><span class="l">external-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">template</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">labels</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">app</span><span class="p">:</span><span class="w"> </span><span class="l">external-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">spec</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">serviceAccountName</span><span class="p">:</span><span class="w"> </span><span class="l">external-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">containers</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">external-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l">registry.k8s.io/external-dns/external-dns:v0.14.2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">args</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span>- --<span class="l">source=service</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span>- --<span class="l">source=ingress</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span>- --<span class="l">provider=rfc2136</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span>- --<span class="l">rfc2136-host=192.168.1.10</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span>- --<span class="l">rfc2136-port=53</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span>- --<span class="l">rfc2136-zone=k8s.example.com</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span>- --<span class="l">rfc2136-tsig-keyname=external-dns-key</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span>- --<span class="l">rfc2136-tsig-secret-alg=hmac-sha256</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span>- --<span class="l">rfc2136-tsig-axfr</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span>- --<span class="l">domain-filter=k8s.example.com</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span>- --<span class="l">policy=sync</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span>- --<span class="l">registry=txt</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span>- --<span class="l">txt-owner-id=k8s-cluster</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span>- --<span class="l">interval=30s</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span>- --<span class="l">log-level=info</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">env</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">EXTERNAL_DNS_RFC2136_TSIG_SECRET</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">              </span><span class="nt">valueFrom</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="nt">secretKeyRef</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">external-dns-tsig</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                  </span><span class="nt">key</span><span class="p">:</span><span class="w"> </span><span class="l">tsig-secret</span><span class="w">
</span></span></span></code></pre></div><h2 id="configuration-options">Configuration Options <a class="anchor" data-pagefind-ignore href="#configuration-options" aria-label="Link to this section">#</a></h2>
<h3 id="key-arguments-explained">Key Arguments Explained <a class="anchor" data-pagefind-ignore href="#key-arguments-explained" aria-label="Link to this section">#</a></h3>
<p><strong>Sources:</strong> which resources External-DNS turns into records.</p>
<ul>
<li><code>--source=service</code> - Watch Kubernetes Services</li>
<li><code>--source=ingress</code> - Watch Ingress resources</li>
<li><code>--source=gateway-httproute</code> - Watch Gateway API HTTPRoutes</li>
</ul>
<p><strong>Provider Settings:</strong> how to reach and authenticate to BIND.</p>
<ul>
<li><code>--provider=rfc2136</code> - Use RFC2136 dynamic DNS</li>
<li><code>--rfc2136-host</code> - BIND server address</li>
<li><code>--rfc2136-port</code> - DNS port. Always set it: the default is <code>0</code>, not 53</li>
<li><code>--rfc2136-zone</code> - Zone to manage</li>
<li><code>--rfc2136-tsig-keyname</code> - TSIG key name (must match BIND config)</li>
<li><code>--rfc2136-tsig-secret-alg</code> - Algorithm (hmac-sha256)</li>
<li><code>--rfc2136-tsig-axfr</code> - Allow zone transfers to read existing records</li>
<li>The TSIG secret itself comes from the <code>EXTERNAL_DNS_RFC2136_TSIG_SECRET</code> environment variable. External-DNS maps every flag to <code>EXTERNAL_DNS_&lt;FLAG&gt;</code>; a plain <code>RFC2136_TSIG_SECRET</code> is ignored and every update fails with <code>dns: bad authentication</code></li>
</ul>
<p><strong>Filtering:</strong> which names and resources are in scope.</p>
<ul>
<li><code>--domain-filter</code> - Only manage records in this domain</li>
<li><code>--namespace</code> - Only watch resources in specific namespace</li>
<li><code>--annotation-filter</code> - Only manage resources with specific annotations</li>
</ul>
<p><strong>Policies:</strong> what External-DNS may do to existing records.</p>
<table>
	<thead>
			<tr>
					<th>Policy</th>
					<th>Creates</th>
					<th>Updates</th>
					<th>Deletes</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>--policy=sync</code></td>
					<td>Yes</td>
					<td>Yes</td>
					<td>Yes</td>
					<td>Full sync; records follow the cluster</td>
			</tr>
			<tr>
					<td><code>--policy=upsert-only</code></td>
					<td>Yes</td>
					<td>Yes</td>
					<td>No</td>
					<td>Getting started, or when deletions are risky</td>
			</tr>
			<tr>
					<td><code>--policy=create-only</code></td>
					<td>Yes</td>
					<td>No</td>
					<td>No</td>
					<td>Only create new records</td>
			</tr>
	</tbody>
</table>
<p><strong>Registry:</strong> how ownership is tracked.</p>
<ul>
<li><code>--registry=txt</code> - Use TXT records to track ownership</li>
<li><code>--txt-owner-id</code> - Unique identifier for this External-DNS instance</li>
</ul>
<h3 id="multiple-zones">Multiple Zones <a class="anchor" data-pagefind-ignore href="#multiple-zones" aria-label="Link to this section">#</a></h3>
<p>To manage multiple zones, deploy multiple External-DNS instances or repeat <code>--rfc2136-zone</code> (supported from v0.14.2; v0.14.0 stops with <code>flag 'rfc2136-zone' cannot be repeated</code>). Add a matching <code>--domain-filter</code> for each:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">args</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- --<span class="l">rfc2136-zone=k8s.example.com</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- --<span class="l">rfc2136-zone=apps.example.com</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- --<span class="l">domain-filter=k8s.example.com</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- --<span class="l">domain-filter=apps.example.com</span><span class="w">
</span></span></span></code></pre></div><h2 id="creating-dns-records">Creating DNS Records <a class="anchor" data-pagefind-ignore href="#creating-dns-records" aria-label="Link to this section">#</a></h2>
<p>How External-DNS finds the hostname depends on the source:</p>
<table>
	<thead>
			<tr>
					<th>Source</th>
					<th>Hostname comes from</th>
					<th>Target comes from</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Service</td>
					<td><code>external-dns.alpha.kubernetes.io/hostname</code> annotation</td>
					<td>The LoadBalancer IP or hostname</td>
			</tr>
			<tr>
					<td>Ingress</td>
					<td><code>spec.rules[].host</code></td>
					<td><code>status.loadBalancer.ingress</code></td>
			</tr>
			<tr>
					<td>HTTPRoute</td>
					<td><code>spec.hostnames</code></td>
					<td>The parent Gateway&rsquo;s address</td>
			</tr>
	</tbody>
</table>
<h3 id="via-services">Via Services <a class="anchor" data-pagefind-ignore href="#via-services" aria-label="Link to this section">#</a></h3>
<p>Use the <code>external-dns.alpha.kubernetes.io/hostname</code> annotation:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">apiVersion</span><span class="p">:</span><span class="w"> </span><span class="l">v1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l">Service</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">my-app</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">annotations</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">external-dns.alpha.kubernetes.io/hostname</span><span class="p">:</span><span class="w"> </span><span class="l">myapp.k8s.example.com</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">spec</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">type</span><span class="p">:</span><span class="w"> </span><span class="l">LoadBalancer</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ports</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">port</span><span class="p">:</span><span class="w"> </span><span class="m">80</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">targetPort</span><span class="p">:</span><span class="w"> </span><span class="m">8080</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">selector</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">app</span><span class="p">:</span><span class="w"> </span><span class="l">my-app</span><span class="w">
</span></span></span></code></pre></div><p>For multiple hostnames, separate them with commas:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">annotations</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">external-dns.alpha.kubernetes.io/hostname</span><span class="p">:</span><span class="w"> </span><span class="l">myapp.k8s.example.com,app.k8s.example.com</span><span class="w">
</span></span></span></code></pre></div><p>Set custom TTL:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">annotations</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">external-dns.alpha.kubernetes.io/hostname</span><span class="p">:</span><span class="w"> </span><span class="l">myapp.k8s.example.com</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">external-dns.alpha.kubernetes.io/ttl</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;60&#34;</span><span class="w">
</span></span></span></code></pre></div><h3 id="via-ingress">Via Ingress <a class="anchor" data-pagefind-ignore href="#via-ingress" aria-label="Link to this section">#</a></h3>
<p>External-DNS automatically uses Ingress hostnames; no annotation needed:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">apiVersion</span><span class="p">:</span><span class="w"> </span><span class="l">networking.k8s.io/v1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l">Ingress</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">my-app-ingress</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">spec</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ingressClassName</span><span class="p">:</span><span class="w"> </span><span class="l">nginx</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">rules</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">host</span><span class="p">:</span><span class="w"> </span><span class="l">myapp.k8s.example.com</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">http</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">paths</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- <span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="l">/</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">pathType</span><span class="p">:</span><span class="w"> </span><span class="l">Prefix</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">backend</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">              </span><span class="nt">service</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">my-app</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="nt">port</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                  </span><span class="nt">number</span><span class="p">:</span><span class="w"> </span><span class="m">80</span><span class="w">
</span></span></span></code></pre></div><p>The Ingress controller must populate the <code>status.loadBalancer.ingress</code> field for External-DNS to determine the target IP.</p>
<h3 id="via-gateway-api">Via Gateway API <a class="anchor" data-pagefind-ignore href="#via-gateway-api" aria-label="Link to this section">#</a></h3>
<p>With Gateway API, External-DNS reads hostnames from HTTPRoute resources. This needs <code>--source=gateway-httproute</code>, which the Deployment above does not set.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">apiVersion</span><span class="p">:</span><span class="w"> </span><span class="l">gateway.networking.k8s.io/v1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l">HTTPRoute</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">my-app-route</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">spec</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">parentRefs</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">my-gateway</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">hostnames</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="l">myapp.k8s.example.com</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">rules</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">matches</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span>- <span class="nt">path</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">type</span><span class="p">:</span><span class="w"> </span><span class="l">PathPrefix</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">value</span><span class="p">:</span><span class="w"> </span><span class="l">/</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">backendRefs</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">my-app</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">port</span><span class="p">:</span><span class="w"> </span><span class="m">80</span><span class="w">
</span></span></span></code></pre></div><h2 id="record-types">Record Types <a class="anchor" data-pagefind-ignore href="#record-types" aria-label="Link to this section">#</a></h2>
<p>External-DNS picks the record type from the target: an IP gives an A record, a hostname a CNAME.</p>
<h3 id="a-records">A Records <a class="anchor" data-pagefind-ignore href="#a-records" aria-label="Link to this section">#</a></h3>
<p>Created automatically for LoadBalancer Services with external IPs:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">apiVersion</span><span class="p">:</span><span class="w"> </span><span class="l">v1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l">Service</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">my-app</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">annotations</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">external-dns.alpha.kubernetes.io/hostname</span><span class="p">:</span><span class="w"> </span><span class="l">myapp.k8s.example.com</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">spec</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">type</span><span class="p">:</span><span class="w"> </span><span class="l">LoadBalancer</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">loadBalancerIP</span><span class="p">:</span><span class="w"> </span><span class="m">192.168.1.100</span><span class="w">  </span><span class="c"># Optional: request specific IP</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ports</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">port</span><span class="p">:</span><span class="w"> </span><span class="m">80</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">selector</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">app</span><span class="p">:</span><span class="w"> </span><span class="l">my-app</span><span class="w">
</span></span></span></code></pre></div><h3 id="cname-records">CNAME Records <a class="anchor" data-pagefind-ignore href="#cname-records" aria-label="Link to this section">#</a></h3>
<p>For services behind cloud load balancers that return hostnames. The <code>target</code> annotation overrides the target External-DNS would otherwise use:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">annotations</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">external-dns.alpha.kubernetes.io/hostname</span><span class="p">:</span><span class="w"> </span><span class="l">myapp.k8s.example.com</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">external-dns.alpha.kubernetes.io/target</span><span class="p">:</span><span class="w"> </span><span class="l">elb.amazonaws.com</span><span class="w">
</span></span></span></code></pre></div><h3 id="txt-records">TXT Records <a class="anchor" data-pagefind-ignore href="#txt-records" aria-label="Link to this section">#</a></h3>
<p>External-DNS creates TXT records to track ownership. It only changes or deletes records whose TXT record carries its own <code>--txt-owner-id</code>:</p>
<pre tabindex="0"><code>myapp.k8s.example.com.    0  IN  A    192.168.1.100
myapp.k8s.example.com.    0  IN  TXT  &#34;heritage=external-dns,external-dns/owner=k8s-cluster,external-dns/resource=service/default/my-app&#34;
a-myapp.k8s.example.com.  0  IN  TXT  &#34;heritage=external-dns,external-dns/owner=k8s-cluster,external-dns/resource=service/default/my-app&#34;
</code></pre><p>Without a <code>ttl</code> annotation the records get TTL 0. The <code>a-</code> record is the newer per-record-type ownership format, written next to the old one.</p>
<p>This prevents External-DNS from accidentally modifying records it didn&rsquo;t create.</p>
<h2 id="advanced-configuration">Advanced Configuration <a class="anchor" data-pagefind-ignore href="#advanced-configuration" aria-label="Link to this section">#</a></h2>
<h3 id="multiple-clusters">Multiple Clusters <a class="anchor" data-pagefind-ignore href="#multiple-clusters" aria-label="Link to this section">#</a></h3>
<p>When multiple clusters share a zone, use different owner IDs. Each cluster then only manages its own records. A per-cluster <code>--txt-prefix</code> keeps their TXT records apart.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="c"># Cluster 1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">args</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- --<span class="l">txt-owner-id=cluster-prod</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- --<span class="l">txt-prefix=_edns-prod-</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># Cluster 2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">args</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- --<span class="l">txt-owner-id=cluster-staging</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- --<span class="l">txt-prefix=_edns-staging-</span><span class="w">
</span></span></span></code></pre></div><h3 id="filtering-by-annotation">Filtering by Annotation <a class="anchor" data-pagefind-ignore href="#filtering-by-annotation" aria-label="Link to this section">#</a></h3>
<p>Opt-in mode: External-DNS ignores every resource without the annotation. Useful when not every Service should be in DNS.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">args</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- --<span class="l">annotation-filter=external-dns.alpha.kubernetes.io/enabled=true</span><span class="w">
</span></span></span></code></pre></div><p>Then annotate resources explicitly:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">annotations</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">external-dns.alpha.kubernetes.io/enabled</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;true&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">external-dns.alpha.kubernetes.io/hostname</span><span class="p">:</span><span class="w"> </span><span class="l">myapp.k8s.example.com</span><span class="w">
</span></span></span></code></pre></div><h3 id="namespace-filtering">Namespace Filtering <a class="anchor" data-pagefind-ignore href="#namespace-filtering" aria-label="Link to this section">#</a></h3>
<p>Limit External-DNS to a specific namespace. <code>--namespace</code> takes a single value (repeating it fails with <code>flag 'namespace' cannot be repeated</code>), so run one instance per namespace if you need several:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">args</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- --<span class="l">namespace=production</span><span class="w">
</span></span></span></code></pre></div><h3 id="internal-vs-external-records">Internal vs External Records <a class="anchor" data-pagefind-ignore href="#internal-vs-external-records" aria-label="Link to this section">#</a></h3>
<p>Run two External-DNS instances for split-horizon DNS. Each points at its own BIND server and zone, and the <code>internal</code> annotation decides which instance handles a resource:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="c"># Internal DNS (for internal services)</span><span class="w">
</span></span></span><span class="line"><span class="cl">- --<span class="l">source=service</span><span class="w">
</span></span></span><span class="line"><span class="cl">- --<span class="l">rfc2136-host=internal-dns.example.com</span><span class="w">
</span></span></span><span class="line"><span class="cl">- --<span class="l">rfc2136-zone=internal.k8s.example.com</span><span class="w">
</span></span></span><span class="line"><span class="cl">- --<span class="l">annotation-filter=external-dns.alpha.kubernetes.io/internal=true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># External DNS (for public services)</span><span class="w">
</span></span></span><span class="line"><span class="cl">- --<span class="l">source=ingress</span><span class="w">
</span></span></span><span class="line"><span class="cl">- --<span class="l">rfc2136-host=external-dns.example.com</span><span class="w">
</span></span></span><span class="line"><span class="cl">- --<span class="l">rfc2136-zone=k8s.example.com</span><span class="w">
</span></span></span><span class="line"><span class="cl">- --<span class="l">annotation-filter=external-dns.alpha.kubernetes.io/internal notin (true)</span><span class="w">
</span></span></span></code></pre></div><p>The annotation filter uses label selector syntax, but <code>!=</code> is rejected (<code>&quot;!=&quot; is not a valid label selector operator</code>); <code>notin (true)</code> does the same job.</p>
<h2 id="helm-installation">Helm Installation <a class="anchor" data-pagefind-ignore href="#helm-installation" aria-label="Link to this section">#</a></h2>
<p>For production deployments, use the Helm chart. It creates the ServiceAccount, RBAC and Deployment for you; you only pass the settings.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">helm repo add external-dns https://kubernetes-sigs.github.io/external-dns/
</span></span><span class="line"><span class="cl">helm repo update
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">helm install external-dns external-dns/external-dns <span class="se">\
</span></span></span><span class="line"><span class="cl">  --namespace external-dns <span class="se">\
</span></span></span><span class="line"><span class="cl">  --create-namespace <span class="se">\
</span></span></span><span class="line"><span class="cl">  --set provider.name<span class="o">=</span>rfc2136 <span class="se">\
</span></span></span><span class="line"><span class="cl">  --set extraArgs<span class="o">[</span>0<span class="o">]=</span>--rfc2136-host<span class="o">=</span>192.168.1.10 <span class="se">\
</span></span></span><span class="line"><span class="cl">  --set extraArgs<span class="o">[</span>1<span class="o">]=</span>--rfc2136-port<span class="o">=</span><span class="m">53</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  --set extraArgs<span class="o">[</span>2<span class="o">]=</span>--rfc2136-zone<span class="o">=</span>k8s.example.com <span class="se">\
</span></span></span><span class="line"><span class="cl">  --set extraArgs<span class="o">[</span>3<span class="o">]=</span>--rfc2136-tsig-keyname<span class="o">=</span>external-dns-key <span class="se">\
</span></span></span><span class="line"><span class="cl">  --set extraArgs<span class="o">[</span>4<span class="o">]=</span>--rfc2136-tsig-secret-alg<span class="o">=</span>hmac-sha256 <span class="se">\
</span></span></span><span class="line"><span class="cl">  --set extraArgs<span class="o">[</span>5<span class="o">]=</span>--rfc2136-tsig-axfr <span class="se">\
</span></span></span><span class="line"><span class="cl">  --set extraArgs<span class="o">[</span>6<span class="o">]=</span>--enable-legacy-annotation-prefix <span class="se">\
</span></span></span><span class="line"><span class="cl">  --set domainFilters<span class="o">[</span>0<span class="o">]=</span>k8s.example.com <span class="se">\
</span></span></span><span class="line"><span class="cl">  --set <span class="nv">policy</span><span class="o">=</span>sync <span class="se">\
</span></span></span><span class="line"><span class="cl">  --set <span class="nv">txtOwnerId</span><span class="o">=</span>k8s-cluster <span class="se">\
</span></span></span><span class="line"><span class="cl">  --set env<span class="o">[</span>0<span class="o">]</span>.name<span class="o">=</span>EXTERNAL_DNS_RFC2136_TSIG_SECRET <span class="se">\
</span></span></span><span class="line"><span class="cl">  --set-string env<span class="o">[</span>0<span class="o">]</span>.valueFrom.secretKeyRef.name<span class="o">=</span>external-dns-tsig <span class="se">\
</span></span></span><span class="line"><span class="cl">  --set-string env<span class="o">[</span>0<span class="o">]</span>.valueFrom.secretKeyRef.key<span class="o">=</span>tsig-secret
</span></span></code></pre></div><p>What to know about the chart:</p>
<ul>
<li>The chart has no <code>rfc2136.*</code> values. Unknown keys are silently ignored, so the provider settings go in <code>extraArgs</code>.</li>
<li>The environment variable list is <code>env</code>, not <code>extraEnv</code>.</li>
<li>The chart deploys a current External-DNS release (v0.23 with chart 1.23), which reads <code>external-dns.kubernetes.io/</code> annotations. <code>--enable-legacy-annotation-prefix</code> makes it honour the <code>external-dns.alpha.kubernetes.io/</code> annotations used throughout this post as well.</li>
</ul>
<h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<p>Work from both ends: what External-DNS tried to do, and what BIND did with it.</p>
<h3 id="check-external-dns-logs">Check External-DNS Logs <a class="anchor" data-pagefind-ignore href="#check-external-dns-logs" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">kubectl logs -n external-dns deployment/external-dns -f
</span></span></code></pre></div><table>
	<thead>
			<tr>
					<th>Log message</th>
					<th>Meaning</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>All records are already up to date</code></td>
					<td>Normal operation</td>
			</tr>
			<tr>
					<td><code>Adding RR</code> / <code>Removing RR</code></td>
					<td>Changes being made</td>
			</tr>
			<tr>
					<td><code>dns: bad authentication</code></td>
					<td>TSIG authentication issues</td>
			</tr>
			<tr>
					<td><code>REFUSED</code></td>
					<td>BIND rejecting updates</td>
			</tr>
	</tbody>
</table>
<h3 id="verify-bind-received-updates">Verify BIND Received Updates <a class="anchor" data-pagefind-ignore href="#verify-bind-received-updates" aria-label="Link to this section">#</a></h3>
<p>Enable update logging in BIND. named accepts only one <code>logging</code> block, so if your <code>named.conf</code> already has one (the RHEL default does), add the channel and categories to it instead of adding a second block:</p>
<pre tabindex="0"><code>logging {
    channel update_log {
        file &#34;/var/log/named/update.log&#34; versions 5 size 10m;
        severity debug;
        print-time yes;
    };
    category update { update_log; };
    category update-security { update_log; };
};
</code></pre><h3 id="test-connectivity">Test Connectivity <a class="anchor" data-pagefind-ignore href="#test-connectivity" aria-label="Link to this section">#</a></h3>
<p>Check that pods can reach BIND at all. The External-DNS image is distroless and has no <code>nslookup</code>, so use a throwaway pod in the same namespace:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">kubectl run -n external-dns dnstest --rm -it --image<span class="o">=</span>busybox:1.37 --restart<span class="o">=</span>Never -- <span class="se">\
</span></span></span><span class="line"><span class="cl">  nslookup -type<span class="o">=</span>SOA k8s.example.com 192.168.1.10
</span></span></code></pre></div><h3 id="manual-dns-test">Manual DNS Test <a class="anchor" data-pagefind-ignore href="#manual-dns-test" aria-label="Link to this section">#</a></h3>
<p>Send an update by hand with the same key. If this works, BIND and the key are fine and the problem is on the External-DNS side.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">nsupdate -v <span class="s">&lt;&lt; EOF
</span></span></span><span class="line"><span class="cl"><span class="s">server 192.168.1.10
</span></span></span><span class="line"><span class="cl"><span class="s">key hmac-sha256:external-dns-key &lt;secret&gt;
</span></span></span><span class="line"><span class="cl"><span class="s">zone k8s.example.com
</span></span></span><span class="line"><span class="cl"><span class="s">update add test.k8s.example.com 300 A 192.168.1.99
</span></span></span><span class="line"><span class="cl"><span class="s">send
</span></span></span><span class="line"><span class="cl"><span class="s">EOF</span>
</span></span></code></pre></div><p>Without the <code>hmac-sha256:</code> prefix, <code>nsupdate</code> assumes hmac-md5 and the update fails with <code>NOTAUTH(BADKEY)</code>. Alternatively, pass the key file: <code>nsupdate -k /etc/named/keys/external-dns.key</code>.</p>
<h3 id="common-issues">Common Issues <a class="anchor" data-pagefind-ignore href="#common-issues" aria-label="Link to this section">#</a></h3>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Check</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Records not created</td>
					<td><code>--domain-filter</code> matches your hostnames; Service has <code>status.loadBalancer.ingress</code> populated; annotation spelling</td>
			</tr>
			<tr>
					<td>TSIG authentication failed</td>
					<td>Key name matches exactly; algorithm matches (hmac-sha256); secret is correctly encoded in the Kubernetes secret</td>
			</tr>
			<tr>
					<td>Records deleted unexpectedly</td>
					<td><code>--policy</code> setting (use <code>upsert-only</code> to prevent deletions); TXT ownership records exist; <code>--txt-owner-id</code> matches</td>
			</tr>
	</tbody>
</table>
<h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<p>The TSIG key can change DNS records. Limit what it may change and who can reach BIND with it.</p>
<h3 id="limit-zone-access">Limit Zone Access <a class="anchor" data-pagefind-ignore href="#limit-zone-access" aria-label="Link to this section">#</a></h3>
<p>Restrict External-DNS to specific subdomains:</p>
<pre tabindex="0"><code>update-policy {
    grant external-dns-key subdomain k8s.example.com ANY;
};
</code></pre><h3 id="network-policies">Network Policies <a class="anchor" data-pagefind-ignore href="#network-policies" aria-label="Link to this section">#</a></h3>
<p>Restrict External-DNS network access. External-DNS only needs two destinations: BIND on port 53 (UDP and TCP, the latter for zone transfers) and the Kubernetes API.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">apiVersion</span><span class="p">:</span><span class="w"> </span><span class="l">networking.k8s.io/v1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l">NetworkPolicy</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">external-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">namespace</span><span class="p">:</span><span class="w"> </span><span class="l">external-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">spec</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">podSelector</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">matchLabels</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">app</span><span class="p">:</span><span class="w"> </span><span class="l">external-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">policyTypes</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="l">Egress</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">egress</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># Allow DNS to BIND server</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">to</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span>- <span class="nt">ipBlock</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">cidr</span><span class="p">:</span><span class="w"> </span><span class="m">192.168.1.10</span><span class="l">/32</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ports</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span>- <span class="nt">protocol</span><span class="p">:</span><span class="w"> </span><span class="l">UDP</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">port</span><span class="p">:</span><span class="w"> </span><span class="m">53</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span>- <span class="nt">protocol</span><span class="p">:</span><span class="w"> </span><span class="l">TCP</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">port</span><span class="p">:</span><span class="w"> </span><span class="m">53</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># Allow API server access. The kubernetes Service (443) is translated</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># to the control-plane endpoints (usually :6443) before the policy is</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># checked, and those are host IPs that no namespaceSelector matches.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">to</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span>- <span class="nt">ipBlock</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">cidr</span><span class="p">:</span><span class="w"> </span><span class="m">192.168.1.20</span><span class="l">/32 </span><span class="w"> </span><span class="c"># your control-plane node(s)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ports</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span>- <span class="nt">protocol</span><span class="p">:</span><span class="w"> </span><span class="l">TCP</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">port</span><span class="p">:</span><span class="w"> </span><span class="m">443</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span>- <span class="nt">protocol</span><span class="p">:</span><span class="w"> </span><span class="l">TCP</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">port</span><span class="p">:</span><span class="w"> </span><span class="m">6443</span><span class="w">
</span></span></span></code></pre></div><p>Find the real API server addresses with <code>kubectl get endpointslices -n default -l kubernetes.io/service-name=kubernetes</code>.</p>
<h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub:
<a href="https://github.com/pderuiter/blog-k8s-external-dns-bind" rel="noopener">pderuiter/blog-k8s-external-dns-bind</a>. It creates a BIND server with the TSIG key and dynamic zone, plus a single-node k3s cluster running External-DNS with the RBAC, Deployment and NetworkPolicy from this post. Run <code>terraform apply</code>, then <code>ansible-playbook site.yml</code>; <code>tests/verify.yml</code> checks that a Service&rsquo;s record appears and disappears.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>External-DNS with BIND gives Kubernetes automatic DNS records while BIND stays your authoritative server. RFC2136 updates with a scoped TSIG key keep it under your control.</p>
<p>The next post will cover Response Policy Zones (RPZ) for implementing DNS-based security filtering and blocking.</p>
]]></content:encoded></item><item><title>Monitoring BIND DNS with Prometheus and Grafana</title><link>https://blog.bsdserver.nl/monitoring-bind-dns-with-prometheus-and-grafana/</link><guid isPermaLink="false">693b6f7d79eb54000160a5c8</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:27:25 +0000</pubDate><description>A well-monitored DNS infrastructure provides visibility into query patterns, performance bottlenecks, and potential security issues.</description><category>BIND</category><category>DNS</category><category>Prometheus</category><category>Grafana</category><category>Monitoring</category><category>Observability</category><category>Homelab</category><category>Linux</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/monitoring-bind-dns-with-prometheus.png" medium="image"/><content:encoded><![CDATA[<p>A well-monitored DNS infrastructure provides visibility into query patterns, performance bottlenecks, and potential security issues. Without it, you hear about DNS problems from your users.</p>
<p>This final post in the BIND series sets up monitoring with Prometheus and Grafana: an exporter on every BIND server, dashboards, alerts, and query logs in Loki. It ends with a Docker Compose stack that runs it all on the DNS server.</p>
<h2 id="why-prometheus-and-grafana-for-bind">Why Prometheus and Grafana for BIND? <a class="anchor" data-pagefind-ignore href="#why-prometheus-and-grafana-for-bind" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Metrics without parsing logs</strong>: BIND&rsquo;s statistics channel already counts queries, responses and resolver activity.</li>
<li><strong>Alerting</strong>: Prometheus rules catch SERVFAIL spikes, failed zone transfers and floods.</li>
<li><strong>Dashboards</strong>: a ready-made Grafana dashboard, plus panels you can build yourself.</li>
<li><strong>One stack</strong>: if you already run Prometheus for other services, BIND is one more scrape target.</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> for any BIND server others depend on, especially resolvers and slaves.</li>
<li><strong>Skip the full stack</strong> for a single lab resolver. <code>rndc stats</code> or a look at the statistics channel may be enough.</li>
</ul>
<h3 id="bind-statistics-sources">BIND statistics sources <a class="anchor" data-pagefind-ignore href="#bind-statistics-sources" aria-label="Link to this section">#</a></h3>
<p>BIND provides extensive statistics through several channels:</p>
<table>
	<thead>
			<tr>
					<th>Source</th>
					<th>What you get</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Statistics channel</td>
					<td>XML/JSON HTTP endpoint with counters</td>
					<td>Prometheus, via bind_exporter</td>
			</tr>
			<tr>
					<td>Query logging</td>
					<td>Detailed query/response logs</td>
					<td>Per-domain and per-client analysis in Loki</td>
			</tr>
			<tr>
					<td>RNDC statistics</td>
					<td>Command-line statistics dump</td>
					<td>Ad-hoc checks</td>
			</tr>
	</tbody>
</table>
<h2 id="architecture-overview">Architecture Overview <a class="anchor" data-pagefind-ignore href="#architecture-overview" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>BIND statistics channel</td>
					<td>Every DNS server, <code>127.0.0.1:8053</code></td>
					<td>Serves BIND&rsquo;s counters over HTTP.</td>
			</tr>
			<tr>
					<td>bind_exporter</td>
					<td>Every DNS server, port 9119</td>
					<td>Reads the statistics channel and turns it into Prometheus metrics.</td>
			</tr>
			<tr>
					<td>Prometheus</td>
					<td>Monitoring host (or the DNS server, with Compose)</td>
					<td>Scrapes the exporters, stores metrics, evaluates alert rules.</td>
			</tr>
			<tr>
					<td>Alertmanager</td>
					<td>Next to Prometheus</td>
					<td>Groups alerts and sends notifications.</td>
			</tr>
			<tr>
					<td>Grafana</td>
					<td>Next to Prometheus</td>
					<td>Dashboards.</td>
			</tr>
			<tr>
					<td>Promtail + Loki (optional)</td>
					<td>DNS server, log host</td>
					<td>Ship and store the query log.</td>
			</tr>
	</tbody>
</table>
<p>The flow: BIND → statistics channel → bind_exporter → Prometheus → Grafana dashboards and Alertmanager.</p>
<h2 id="enabling-bind-statistics-channel">Enabling BIND Statistics Channel <a class="anchor" data-pagefind-ignore href="#enabling-bind-statistics-channel" aria-label="Link to this section">#</a></h2>
<h3 id="configure-statistics-in-bind">Configure Statistics in BIND <a class="anchor" data-pagefind-ignore href="#configure-statistics-in-bind" aria-label="Link to this section">#</a></h3>
<p>The statistics channel is a small HTTP server inside BIND. Keep it on localhost: the exporter runs on the same machine, and the statistics reveal a lot about your server.</p>
<ul>
<li><code>statistics-channels</code>: where the endpoint listens, and who may connect (<code>allow { localhost; }</code>).</li>
<li><code>zone-statistics full</code>: also count queries per zone.</li>
</ul>
<pre tabindex="0"><code class="language-named" data-lang="named">// /etc/bind/named.conf.options

// Enable statistics channel (a top-level statement, not an option)
statistics-channels {
    inet 127.0.0.1 port 8053 allow { localhost; };
    inet ::1 port 8053 allow { localhost; };
};

options {
    directory &#34;/var/cache/bind&#34;;
    
    // Enable zone statistics
    zone-statistics full;
    
    // Other options...
    recursion yes;
    dnssec-validation auto;
};
</code></pre><h3 id="verify-statistics-channel">Verify Statistics Channel <a class="anchor" data-pagefind-ignore href="#verify-statistics-channel" aria-label="Link to this section">#</a></h3>
<p>Restart BIND and check that the endpoint answers before you install the exporter:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Restart BIND</span>
</span></span><span class="line"><span class="cl">systemctl restart named
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test statistics endpoint (XML)</span>
</span></span><span class="line"><span class="cl">curl http://127.0.0.1:8053/
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Get XML statistics</span>
</span></span><span class="line"><span class="cl">curl http://127.0.0.1:8053/xml/v3/server
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Get JSON statistics (BIND 9.10+)</span>
</span></span><span class="line"><span class="cl">curl http://127.0.0.1:8053/json/v1/server
</span></span></code></pre></div><h2 id="installing-bind_exporter">Installing bind_exporter <a class="anchor" data-pagefind-ignore href="#installing-bind_exporter" aria-label="Link to this section">#</a></h2>
<p>The bind_exporter converts BIND statistics to Prometheus metrics format. Install it on every BIND server.</p>
<h3 id="download-and-install">Download and Install <a class="anchor" data-pagefind-ignore href="#download-and-install" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Download latest release</span>
</span></span><span class="line"><span class="cl">wget https://github.com/prometheus-community/bind_exporter/releases/download/v0.7.0/bind_exporter-0.7.0.linux-amd64.tar.gz
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Extract</span>
</span></span><span class="line"><span class="cl">tar xzf bind_exporter-0.7.0.linux-amd64.tar.gz
</span></span><span class="line"><span class="cl">mv bind_exporter-0.7.0.linux-amd64/bind_exporter /usr/local/bin/
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Set permissions</span>
</span></span><span class="line"><span class="cl">chmod +x /usr/local/bin/bind_exporter
</span></span></code></pre></div><h3 id="create-systemd-service">Create Systemd Service <a class="anchor" data-pagefind-ignore href="#create-systemd-service" aria-label="Link to this section">#</a></h3>
<p>The exporter needs no privileges, so it runs as <code>nobody</code>.</p>
<ul>
<li><code>--bind.stats-url</code>: the local statistics channel.</li>
<li><code>--bind.stats-groups</code>: which parts of the statistics to export (table below).</li>
<li><code>--web.listen-address=:9119</code>: where Prometheus scrapes it. It listens on all interfaces; firewall it to your Prometheus host.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-ini" data-lang="ini"><span class="line"><span class="cl"><span class="c1"># /etc/systemd/system/bind_exporter.service</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">[Unit]</span>
</span></span><span class="line"><span class="cl"><span class="na">Description</span><span class="o">=</span><span class="s">BIND Exporter for Prometheus</span>
</span></span><span class="line"><span class="cl"><span class="na">After</span><span class="o">=</span><span class="s">network.target named.service</span>
</span></span><span class="line"><span class="cl"><span class="na">Wants</span><span class="o">=</span><span class="s">named.service</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">[Service]</span>
</span></span><span class="line"><span class="cl"><span class="na">Type</span><span class="o">=</span><span class="s">simple</span>
</span></span><span class="line"><span class="cl"><span class="na">User</span><span class="o">=</span><span class="s">nobody</span>
</span></span><span class="line"><span class="cl"><span class="na">Group</span><span class="o">=</span><span class="s">nogroup</span>
</span></span><span class="line"><span class="cl"><span class="na">ExecStart</span><span class="o">=</span><span class="s">/usr/local/bin/bind_exporter \
</span></span></span><span class="line"><span class="cl"><span class="s">    --bind.stats-url=http://127.0.0.1:8053/ \
</span></span></span><span class="line"><span class="cl"><span class="s">    --bind.stats-groups=server,view,tasks \
</span></span></span><span class="line"><span class="cl"><span class="s">    --web.listen-address=:9119</span>
</span></span><span class="line"><span class="cl"><span class="na">Restart</span><span class="o">=</span><span class="s">always</span>
</span></span><span class="line"><span class="cl"><span class="na">RestartSec</span><span class="o">=</span><span class="s">5</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">[Install]</span>
</span></span><span class="line"><span class="cl"><span class="na">WantedBy</span><span class="o">=</span><span class="s">multi-user.target</span>
</span></span></code></pre></div><p>Enable it and check the metrics:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">systemctl daemon-reload
</span></span><span class="line"><span class="cl">systemctl <span class="nb">enable</span> bind_exporter
</span></span><span class="line"><span class="cl">systemctl start bind_exporter
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test metrics endpoint</span>
</span></span><span class="line"><span class="cl">curl http://localhost:9119/metrics
</span></span></code></pre></div><h3 id="available-statistics-groups">Available Statistics Groups <a class="anchor" data-pagefind-ignore href="#available-statistics-groups" aria-label="Link to this section">#</a></h3>
<p>The exporter supports these statistics groups:</p>
<table>
	<thead>
			<tr>
					<th>Group</th>
					<th>Description</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>server</td>
					<td>Overall server statistics</td>
			</tr>
			<tr>
					<td>view</td>
					<td>Per-view statistics</td>
			</tr>
			<tr>
					<td>tasks</td>
					<td>Task manager statistics</td>
			</tr>
	</tbody>
</table>
<h2 id="prometheus-configuration">Prometheus Configuration <a class="anchor" data-pagefind-ignore href="#prometheus-configuration" aria-label="Link to this section">#</a></h2>
<h3 id="add-scrape-target">Add Scrape Target <a class="anchor" data-pagefind-ignore href="#add-scrape-target" aria-label="Link to this section">#</a></h3>
<p>Add one target per DNS server. The <code>relabel_configs</code> strip the port from the <code>instance</code> label, so graphs show <code>dns1.example.com</code> instead of <code>dns1.example.com:9119</code>. Leave it out if you use dashboard 12309 (see below).</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="c"># /etc/prometheus/prometheus.yml</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">global</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">scrape_interval</span><span class="p">:</span><span class="w"> </span><span class="l">15s</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">evaluation_interval</span><span class="p">:</span><span class="w"> </span><span class="l">15s</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">scrape_configs</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">job_name</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;prometheus&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">static_configs</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">targets</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s1">&#39;localhost:9090&#39;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">job_name</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;bind&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">static_configs</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">targets</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- <span class="s1">&#39;dns1.example.com:9119&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- <span class="s1">&#39;dns2.example.com:9119&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">relabel_configs</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">source_labels</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="l">__address__]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">target_label</span><span class="p">:</span><span class="w"> </span><span class="l">instance</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">regex</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;([^:]+).*&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">replacement</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;${1}&#39;</span><span class="w">
</span></span></span></code></pre></div><p>bind_exporter has no multi-target mode: it always scrapes the one <code>--bind.stats-url</code> it was started with and ignores a <code>?target=</code> parameter. Run one exporter per BIND server (as above), since the statistics channel should only listen on localhost anyway.</p>
<h3 id="reload-prometheus">Reload Prometheus <a class="anchor" data-pagefind-ignore href="#reload-prometheus" aria-label="Link to this section">#</a></h3>
<p>Either command makes Prometheus read the new configuration without a restart:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nb">kill</span> -HUP <span class="k">$(</span>pidof prometheus<span class="k">)</span>
</span></span><span class="line"><span class="cl"><span class="c1"># Or</span>
</span></span><span class="line"><span class="cl">systemctl reload prometheus
</span></span></code></pre></div><h2 id="key-metrics-to-monitor">Key Metrics to Monitor <a class="anchor" data-pagefind-ignore href="#key-metrics-to-monitor" aria-label="Link to this section">#</a></h2>
<p>Most BIND metrics are counters, so wrap them in <code>rate()</code> or <code>increase()</code> to get something you can read.</p>
<h3 id="query-metrics">Query Metrics <a class="anchor" data-pagefind-ignore href="#query-metrics" aria-label="Link to this section">#</a></h3>
<p>How much traffic, of which type, and how it was answered. Note the two response metrics: <code>bind_responses_total</code> groups by result (NOERROR is &ldquo;Success&rdquo;), <code>bind_response_rcodes_total</code> by real RCODE.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-promql" data-lang="promql"><span class="line"><span class="cl"><span class="c1"># Total queries received</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nv">bind_incoming_queries_total</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c1"># Queries by type (A, AAAA, MX, etc.)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nv">bind_incoming_queries_total</span><span class="p">{</span><span class="nl">type</span><span class="o">=</span><span class="p">&#34;</span><span class="s">A</span><span class="p">&#34;}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c1"># Query rate (queries per second)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="kr">rate</span><span class="o">(</span><span class="nv">bind_incoming_queries_total</span><span class="p">[</span><span class="s">5m</span><span class="p">]</span><span class="o">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c1"># Queries by result (NOERROR answers are counted as &#34;Success&#34;)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nv">bind_responses_total</span><span class="p">{</span><span class="nl">result</span><span class="o">=</span><span class="p">&#34;</span><span class="s">Success</span><span class="p">&#34;}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nv">bind_responses_total</span><span class="p">{</span><span class="nl">result</span><span class="o">=</span><span class="p">&#34;</span><span class="s">NXDOMAIN</span><span class="p">&#34;}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nv">bind_responses_total</span><span class="p">{</span><span class="nl">result</span><span class="o">=</span><span class="p">&#34;</span><span class="s">SERVFAIL</span><span class="p">&#34;}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c1"># Responses by real RCODE</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nv">bind_response_rcodes_total</span><span class="p">{</span><span class="nl">rcode</span><span class="o">=</span><span class="p">&#34;</span><span class="s">NOERROR</span><span class="p">&#34;}</span><span class="w">
</span></span></span></code></pre></div><h3 id="resolver-metrics">Resolver Metrics <a class="anchor" data-pagefind-ignore href="#resolver-metrics" aria-label="Link to this section">#</a></h3>
<p>Only relevant on resolvers. A falling cache hit rate or rising upstream latency means slower answers for your clients.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-promql" data-lang="promql"><span class="line"><span class="cl"><span class="c1"># Approximate cache hit rate: share of client queries that needed no recursion</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c1"># (bind_exporter exposes no direct cache hit/miss counters)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="mi">1</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="o">(</span><span class="k">sum</span><span class="o">(</span><span class="kr">rate</span><span class="o">(</span><span class="nv">bind_query_recursions_total</span><span class="p">[</span><span class="s">5m</span><span class="p">]</span><span class="o">))</span><span class="w"> </span><span class="k">by</span><span class="w"> </span><span class="o">(</span><span class="nv">instance</span><span class="o">)</span><span class="w"> </span><span class="o">/</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">     </span><span class="k">sum</span><span class="o">(</span><span class="kr">rate</span><span class="o">(</span><span class="nv">bind_incoming_queries_total</span><span class="p">[</span><span class="s">5m</span><span class="p">]</span><span class="o">))</span><span class="w"> </span><span class="k">by</span><span class="w"> </span><span class="o">(</span><span class="nv">instance</span><span class="o">))</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c1"># Recursive queries sent</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="kr">rate</span><span class="o">(</span><span class="nv">bind_resolver_queries_total</span><span class="p">[</span><span class="s">5m</span><span class="p">]</span><span class="o">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c1"># Response time distribution</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nv">bind_resolver_query_duration_seconds_bucket</span><span class="w">
</span></span></span></code></pre></div><h3 id="server-health-metrics">Server Health Metrics <a class="anchor" data-pagefind-ignore href="#server-health-metrics" aria-label="Link to this section">#</a></h3>
<ul>
<li><code>bind_recursive_clients</code>: recursive queries in progress. Near <code>recursive-clients</code> (default 1000) BIND starts dropping queries.</li>
<li>Zone transfer counters: on slaves, failures mean stale zones.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-promql" data-lang="promql"><span class="line"><span class="cl"><span class="c1"># Current number of recursive clients (exporter 0.8.0 omits it while it is 0)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nv">bind_recursive_clients</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c1"># Zone transfers</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nv">bind_zone_transfer_success_total</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nv">bind_zone_transfer_failure_total</span><span class="w">
</span></span></span></code></pre></div><h2 id="grafana-dashboard">Grafana Dashboard <a class="anchor" data-pagefind-ignore href="#grafana-dashboard" aria-label="Link to this section">#</a></h2>
<h3 id="import-pre-built-dashboard">Import Pre-built Dashboard <a class="anchor" data-pagefind-ignore href="#import-pre-built-dashboard" aria-label="Link to this section">#</a></h3>
<p>The fastest start. The BIND Exporter community provides dashboards:</p>
<ol>
<li>In Grafana, go to Dashboards -&gt; Import</li>
<li>Enter dashboard ID: <strong>12309</strong> (BIND Exporter)</li>
<li>Select your Prometheus data source</li>
<li>Click Import</li>
</ol>
<p>Dashboard 12309 selects series with <code>instance=&quot;$node:$port&quot;</code>, so it expects the default <code>host:port</code> instance label. If you use the <code>relabel_configs</code> above that strip the port, its panels stay empty; leave the relabeling out for this dashboard. Its panels use the legacy graph type, which current Grafana converts automatically on load.</p>
<h3 id="custom-dashboard-panels">Custom Dashboard Panels <a class="anchor" data-pagefind-ignore href="#custom-dashboard-panels" aria-label="Link to this section">#</a></h3>
<p>Build your own panels for what matters to you. Each JSON snippet below is one panel; paste it via a panel&rsquo;s JSON view, or copy the <code>expr</code> into a new panel.</p>
<table>
	<thead>
			<tr>
					<th>Panel</th>
					<th>Type</th>
					<th>Shows</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Query Rate</td>
					<td>Time series</td>
					<td>Queries per second per server</td>
			</tr>
			<tr>
					<td>Query Type Distribution</td>
					<td>Pie chart</td>
					<td>Share of A, AAAA, MX, … over the last hour</td>
			</tr>
			<tr>
					<td>Response Codes</td>
					<td>Stat</td>
					<td>Rate of NOERROR, NXDOMAIN and SERVFAIL</td>
			</tr>
			<tr>
					<td>Cache Hit Rate</td>
					<td>Gauge</td>
					<td>Approximate cache hit rate, red below 70%, green above 90%</td>
			</tr>
	</tbody>
</table>
<h4 id="query-rate-panel">Query Rate Panel <a class="anchor" data-pagefind-ignore href="#query-rate-panel" aria-label="Link to this section">#</a></h4>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json"><span class="line"><span class="cl"><span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;title&#34;</span><span class="p">:</span> <span class="s2">&#34;DNS Query Rate&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;type&#34;</span><span class="p">:</span> <span class="s2">&#34;timeseries&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;targets&#34;</span><span class="p">:</span> <span class="p">[</span>
</span></span><span class="line"><span class="cl">    <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;expr&#34;</span><span class="p">:</span> <span class="s2">&#34;sum(rate(bind_incoming_queries_total[5m])) by (instance)&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;legendFormat&#34;</span><span class="p">:</span> <span class="s2">&#34;{{instance}}&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl">  <span class="p">],</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;fieldConfig&#34;</span><span class="p">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="nt">&#34;defaults&#34;</span><span class="p">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;unit&#34;</span><span class="p">:</span> <span class="s2">&#34;reqps&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;custom&#34;</span><span class="p">:</span> <span class="p">{</span> <span class="nt">&#34;axisLabel&#34;</span><span class="p">:</span> <span class="s2">&#34;Queries/sec&#34;</span> <span class="p">}</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl">  <span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span></code></pre></div><h4 id="query-type-distribution">Query Type Distribution <a class="anchor" data-pagefind-ignore href="#query-type-distribution" aria-label="Link to this section">#</a></h4>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json"><span class="line"><span class="cl"><span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;title&#34;</span><span class="p">:</span> <span class="s2">&#34;Query Types&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;type&#34;</span><span class="p">:</span> <span class="s2">&#34;piechart&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;targets&#34;</span><span class="p">:</span> <span class="p">[</span>
</span></span><span class="line"><span class="cl">    <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;expr&#34;</span><span class="p">:</span> <span class="s2">&#34;sum(increase(bind_incoming_queries_total[1h])) by (type)&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;legendFormat&#34;</span><span class="p">:</span> <span class="s2">&#34;{{type}}&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl">  <span class="p">]</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span></code></pre></div><h4 id="response-codes">Response Codes <a class="anchor" data-pagefind-ignore href="#response-codes" aria-label="Link to this section">#</a></h4>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json"><span class="line"><span class="cl"><span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;title&#34;</span><span class="p">:</span> <span class="s2">&#34;Response Codes&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;type&#34;</span><span class="p">:</span> <span class="s2">&#34;stat&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;targets&#34;</span><span class="p">:</span> <span class="p">[</span>
</span></span><span class="line"><span class="cl">    <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;expr&#34;</span><span class="p">:</span> <span class="s2">&#34;sum(rate(bind_responses_total{result=\&#34;Success\&#34;}[5m]))&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;legendFormat&#34;</span><span class="p">:</span> <span class="s2">&#34;NOERROR&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="p">},</span>
</span></span><span class="line"><span class="cl">    <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;expr&#34;</span><span class="p">:</span> <span class="s2">&#34;sum(rate(bind_responses_total{result=\&#34;NXDOMAIN\&#34;}[5m]))&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;legendFormat&#34;</span><span class="p">:</span> <span class="s2">&#34;NXDOMAIN&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="p">},</span>
</span></span><span class="line"><span class="cl">    <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;expr&#34;</span><span class="p">:</span> <span class="s2">&#34;sum(rate(bind_responses_total{result=\&#34;SERVFAIL\&#34;}[5m]))&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;legendFormat&#34;</span><span class="p">:</span> <span class="s2">&#34;SERVFAIL&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl">  <span class="p">]</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span></code></pre></div><h4 id="cache-hit-rate">Cache Hit Rate <a class="anchor" data-pagefind-ignore href="#cache-hit-rate" aria-label="Link to this section">#</a></h4>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json"><span class="line"><span class="cl"><span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;title&#34;</span><span class="p">:</span> <span class="s2">&#34;Cache Hit Rate&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;type&#34;</span><span class="p">:</span> <span class="s2">&#34;gauge&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;targets&#34;</span><span class="p">:</span> <span class="p">[</span>
</span></span><span class="line"><span class="cl">    <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;expr&#34;</span><span class="p">:</span> <span class="s2">&#34;(1 - sum(rate(bind_query_recursions_total[5m])) / sum(rate(bind_incoming_queries_total[5m]))) * 100&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl">  <span class="p">],</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;fieldConfig&#34;</span><span class="p">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="nt">&#34;defaults&#34;</span><span class="p">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;unit&#34;</span><span class="p">:</span> <span class="s2">&#34;percent&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;min&#34;</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;max&#34;</span><span class="p">:</span> <span class="mi">100</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;thresholds&#34;</span><span class="p">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="nt">&#34;steps&#34;</span><span class="p">:</span> <span class="p">[</span>
</span></span><span class="line"><span class="cl">          <span class="p">{</span><span class="nt">&#34;value&#34;</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span> <span class="nt">&#34;color&#34;</span><span class="p">:</span> <span class="s2">&#34;red&#34;</span><span class="p">},</span>
</span></span><span class="line"><span class="cl">          <span class="p">{</span><span class="nt">&#34;value&#34;</span><span class="p">:</span> <span class="mi">70</span><span class="p">,</span> <span class="nt">&#34;color&#34;</span><span class="p">:</span> <span class="s2">&#34;yellow&#34;</span><span class="p">},</span>
</span></span><span class="line"><span class="cl">          <span class="p">{</span><span class="nt">&#34;value&#34;</span><span class="p">:</span> <span class="mi">90</span><span class="p">,</span> <span class="nt">&#34;color&#34;</span><span class="p">:</span> <span class="s2">&#34;green&#34;</span><span class="p">}</span>
</span></span><span class="line"><span class="cl">        <span class="p">]</span>
</span></span><span class="line"><span class="cl">      <span class="p">}</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl">  <span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span></code></pre></div><h2 id="alerting-rules">Alerting Rules <a class="anchor" data-pagefind-ignore href="#alerting-rules" aria-label="Link to this section">#</a></h2>
<h3 id="prometheus-alert-rules">Prometheus Alert Rules <a class="anchor" data-pagefind-ignore href="#prometheus-alert-rules" aria-label="Link to this section">#</a></h3>
<p>Each rule has a <code>for</code> duration, so a short spike does not page anyone. Tune the thresholds to your normal traffic.</p>
<table>
	<thead>
			<tr>
					<th>Alert</th>
					<th>Fires when</th>
					<th>Why it matters</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>BindHighQueryRate</code></td>
					<td>Over 1000 queries/s for 5 minutes</td>
					<td>Unexpected load or a misbehaving client</td>
			</tr>
			<tr>
					<td><code>BindHighServfailRate</code></td>
					<td>Over 5% SERVFAIL for 5 minutes</td>
					<td>Upstream, DNSSEC or zone problems; clients see failures</td>
			</tr>
			<tr>
					<td><code>BindLowCacheHitRate</code></td>
					<td>Cache hit rate under 70% for 15 minutes</td>
					<td>More recursion, slower answers</td>
			</tr>
			<tr>
					<td><code>BindRecursiveClientsHigh</code></td>
					<td>Over 900 recursive clients for 2 minutes</td>
					<td>Close to the default limit of 1000</td>
			</tr>
			<tr>
					<td><code>BindZoneTransferFailure</code></td>
					<td>Any failed transfer in the last hour</td>
					<td>A slave may serve stale data</td>
			</tr>
			<tr>
					<td><code>BindExporterDown</code></td>
					<td>Exporter unreachable for 2 minutes</td>
					<td>No metrics, so no other alert can fire</td>
			</tr>
	</tbody>
</table>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="c"># /etc/prometheus/rules/bind.yml</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">groups</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">bind</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">rules</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="c"># High query rate</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">alert</span><span class="p">:</span><span class="w"> </span><span class="l">BindHighQueryRate</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">expr</span><span class="p">:</span><span class="w"> </span><span class="l">sum(rate(bind_incoming_queries_total[5m])) by (instance) &gt; 1000</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">for</span><span class="p">:</span><span class="w"> </span><span class="l">5m</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">labels</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">severity</span><span class="p">:</span><span class="w"> </span><span class="l">warning</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">annotations</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">summary</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;High DNS query rate on {{ $labels.instance }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">description</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;Query rate is {{ $value }} queries/sec&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="c"># SERVFAIL rate too high</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">alert</span><span class="p">:</span><span class="w"> </span><span class="l">BindHighServfailRate</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">expr</span><span class="p">:</span><span class="w"> </span><span class="p">|</span><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">          sum(rate(bind_responses_total{result=&#34;SERVFAIL&#34;}[5m])) by (instance) /
</span></span></span><span class="line"><span class="cl"><span class="sd">          sum(rate(bind_responses_total[5m])) by (instance) &gt; 0.05</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">for</span><span class="p">:</span><span class="w"> </span><span class="l">5m</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">labels</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">severity</span><span class="p">:</span><span class="w"> </span><span class="l">critical</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">annotations</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">summary</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;High SERVFAIL rate on {{ $labels.instance }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">description</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;SERVFAIL rate is {{ $value | humanizePercentage }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="c"># Low cache hit rate</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">alert</span><span class="p">:</span><span class="w"> </span><span class="l">BindLowCacheHitRate</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">expr</span><span class="p">:</span><span class="w"> </span><span class="p">|</span><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">          1 - (sum(rate(bind_query_recursions_total[5m])) by (instance) /
</span></span></span><span class="line"><span class="cl"><span class="sd">               sum(rate(bind_incoming_queries_total[5m])) by (instance)) &lt; 0.7</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">for</span><span class="p">:</span><span class="w"> </span><span class="l">15m</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">labels</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">severity</span><span class="p">:</span><span class="w"> </span><span class="l">warning</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">annotations</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">summary</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;Low cache hit rate on {{ $labels.instance }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">description</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;Cache hit rate is {{ $value | humanizePercentage }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="c"># Recursive clients exhausted</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">alert</span><span class="p">:</span><span class="w"> </span><span class="l">BindRecursiveClientsHigh</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">expr</span><span class="p">:</span><span class="w"> </span><span class="l">bind_recursive_clients &gt; 900</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">for</span><span class="p">:</span><span class="w"> </span><span class="l">2m</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">labels</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">severity</span><span class="p">:</span><span class="w"> </span><span class="l">critical</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">annotations</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">summary</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;High recursive clients on {{ $labels.instance }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">description</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;Recursive clients: {{ $value }} (default max: 1000)&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="c"># Zone transfer failures</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">alert</span><span class="p">:</span><span class="w"> </span><span class="l">BindZoneTransferFailure</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">expr</span><span class="p">:</span><span class="w"> </span><span class="l">increase(bind_zone_transfer_failure_total[1h]) &gt; 0</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">for</span><span class="p">:</span><span class="w"> </span><span class="l">0m</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">labels</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">severity</span><span class="p">:</span><span class="w"> </span><span class="l">warning</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">annotations</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">summary</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;Zone transfer failure on {{ $labels.instance }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">description</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;Zone transfers have failed in the last hour&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="c"># Exporter down</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">alert</span><span class="p">:</span><span class="w"> </span><span class="l">BindExporterDown</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">expr</span><span class="p">:</span><span class="w"> </span><span class="l">up{job=&#34;bind&#34;} == 0</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">for</span><span class="p">:</span><span class="w"> </span><span class="l">2m</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">labels</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">severity</span><span class="p">:</span><span class="w"> </span><span class="l">critical</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">annotations</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">summary</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;BIND exporter down on {{ $labels.instance }}&#34;</span><span class="w">
</span></span></span></code></pre></div><h2 id="query-logging-for-analysis">Query Logging for Analysis <a class="anchor" data-pagefind-ignore href="#query-logging-for-analysis" aria-label="Link to this section">#</a></h2>
<p>Metrics give totals; the query log says which client asked for which name. Enable it when you need that detail. It costs disk space and some performance on busy servers.</p>
<h3 id="enable-query-logging">Enable Query Logging <a class="anchor" data-pagefind-ignore href="#enable-query-logging" aria-label="Link to this section">#</a></h3>
<p>Separate files for queries and security events, rotated by size (<code>versions</code> and <code>size</code>):</p>
<pre tabindex="0"><code class="language-named" data-lang="named">// /etc/bind/named.conf

logging {
    channel query_log {
        file &#34;/var/log/named/queries.log&#34; versions 10 size 100m;
        severity info;
        print-time yes;
        print-category yes;
        print-severity yes;
    };
    
    channel security_log {
        file &#34;/var/log/named/security.log&#34; versions 5 size 50m;
        severity info;
        print-time yes;
        print-category yes;
    };
    
    category queries { query_log; };
    category security { security_log; };
    category query-errors { query_log; };
};
</code></pre><p>Defining the <code>queries</code> category does not switch query logging on: it is enabled at startup, but <code>rndc reconfig</code> or <code>rndc reload</code> leaves it off. Turn it on with <code>rndc querylog on</code>, or add <code>querylog yes;</code> to <code>options</code> so it survives reloads.</p>
<h3 id="parse-logs-with-promtailloki">Parse Logs with Promtail/Loki <a class="anchor" data-pagefind-ignore href="#parse-logs-with-promtailloki" aria-label="Link to this section">#</a></h3>
<p>Promtail ships the logs to Loki. The <code>regex</code> stage pulls client IP, domain and type out of each query line, and the <code>timestamp</code> stage uses BIND&rsquo;s time instead of the read time.</p>
<p><code>client_ip</code> and <code>domain</code> as labels create a Loki stream per client and per name. That is fine for a small server; on a busy one, keep them out of the labels and extract them at query time instead.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="c"># /etc/promtail/promtail.yml</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">server</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">http_listen_port</span><span class="p">:</span><span class="w"> </span><span class="m">9080</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">positions</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">filename</span><span class="p">:</span><span class="w"> </span><span class="l">/var/lib/promtail/positions.yaml</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">clients</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">url</span><span class="p">:</span><span class="w"> </span><span class="l">http://loki:3100/loki/api/v1/push</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">scrape_configs</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">job_name</span><span class="p">:</span><span class="w"> </span><span class="l">bind_queries</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">static_configs</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">targets</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- <span class="l">localhost</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">labels</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">job</span><span class="p">:</span><span class="w"> </span><span class="l">bind_queries</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">__path__</span><span class="p">:</span><span class="w"> </span><span class="l">/var/log/named/queries.log</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">pipeline_stages</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">regex</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">expression</span><span class="p">:</span><span class="w"> </span><span class="nt">&#39;^(?P&lt;timestamp&gt;\d+-\w+-\d+ \d+:\d+:\d+.\d+) queries</span><span class="p">:</span><span class="w"> </span><span class="nt">info</span><span class="p">:</span><span class="w"> </span><span class="l">client @\S+ (?P&lt;client_ip&gt;[\d.]+)#\d+ \((?P&lt;query&gt;[^)]+)\): query: (?P&lt;domain&gt;\S+) IN (?P&lt;type&gt;\w+)&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">labels</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">client_ip</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">query</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">domain</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">type</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">timestamp</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">source</span><span class="p">:</span><span class="w"> </span><span class="l">timestamp</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">format</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;02-Jan-2006 15:04:05.000&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">job_name</span><span class="p">:</span><span class="w"> </span><span class="l">bind_security</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">static_configs</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">targets</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- <span class="l">localhost</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">labels</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">job</span><span class="p">:</span><span class="w"> </span><span class="l">bind_security</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">__path__</span><span class="p">:</span><span class="w"> </span><span class="l">/var/log/named/security.log</span><span class="w">
</span></span></span></code></pre></div><h2 id="complete-monitoring-stack-with-docker-compose">Complete Monitoring Stack with Docker Compose <a class="anchor" data-pagefind-ignore href="#complete-monitoring-stack-with-docker-compose" aria-label="Link to this section">#</a></h2>
<p>Deploy a complete monitoring stack on the DNS server itself. Good for a single server or a lab; for several DNS servers, run Prometheus and Grafana once, centrally.</p>
<p>The statistics channel only listens on 127.0.0.1 with <code>allow { localhost; }</code>, so a bind_exporter container on a Docker bridge network cannot reach it. Run the exporter with <code>network_mode: host</code> instead: it then talks to 127.0.0.1:8053 like the systemd service above, and listens on the host&rsquo;s port 9119. Prometheus reaches it through <code>host.docker.internal</code>. Use either this container or the systemd service, not both, because both listen on port 9119.</p>
<pre tabindex="0"><code>bind-monitoring/
├── docker-compose.yml
├── .env
├── prometheus/
│   ├── prometheus.yml
│   └── rules/
│       ├── bind.yml
│       └── bind_security.yml
├── alertmanager/
│   └── alertmanager.yml
└── grafana/
    └── provisioning/
        └── datasources/
            └── prometheus.yml
</code></pre><p>The services:</p>
<ul>
<li><code>prometheus</code>: <code>--web.enable-lifecycle</code> allows reloads over HTTP; <code>extra_hosts</code> maps <code>host.docker.internal</code> to the host.</li>
<li><code>grafana</code>: admin password from <code>.env</code>, sign-up disabled.</li>
<li><code>alertmanager</code>: receives alerts from Prometheus.</li>
<li><code>bind_exporter</code>: on the host network, as explained above.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="c"># docker-compose.yml</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">services</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">prometheus</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l">prom/prometheus:v3.16.0</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">container_name</span><span class="p">:</span><span class="w"> </span><span class="l">prometheus</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">restart</span><span class="p">:</span><span class="w"> </span><span class="l">unless-stopped</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">volumes</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">./prometheus:/etc/prometheus</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">prometheus_data:/prometheus</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">command</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s1">&#39;--config.file=/etc/prometheus/prometheus.yml&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s1">&#39;--storage.tsdb.path=/prometheus&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s1">&#39;--web.enable-lifecycle&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">ports</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s2">&#34;9090:9090&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">extra_hosts</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s2">&#34;host.docker.internal:host-gateway&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">networks</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">monitoring</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">grafana</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l">grafana/grafana:13.3.1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">container_name</span><span class="p">:</span><span class="w"> </span><span class="l">grafana</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">restart</span><span class="p">:</span><span class="w"> </span><span class="l">unless-stopped</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">volumes</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">grafana_data:/var/lib/grafana</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">./grafana/provisioning:/etc/grafana/provisioning</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">environment</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_ADMIN_PASSWORD}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">GF_USERS_ALLOW_SIGN_UP=false</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">ports</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s2">&#34;3000:3000&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">networks</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">monitoring</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">alertmanager</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l">prom/alertmanager:v0.33.1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">container_name</span><span class="p">:</span><span class="w"> </span><span class="l">alertmanager</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">restart</span><span class="p">:</span><span class="w"> </span><span class="l">unless-stopped</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">volumes</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">./alertmanager:/etc/alertmanager</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">command</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s1">&#39;--config.file=/etc/alertmanager/alertmanager.yml&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">ports</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s2">&#34;9093:9093&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">networks</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">monitoring</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="c"># Host network: the statistics channel only listens on 127.0.0.1:8053 (allow localhost).</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="c"># The exporter listens on the host&#39;s port 9119; Prometheus reaches it via host.docker.internal.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">bind_exporter</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l">prometheuscommunity/bind-exporter:v0.7.0</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">container_name</span><span class="p">:</span><span class="w"> </span><span class="l">bind_exporter</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">restart</span><span class="p">:</span><span class="w"> </span><span class="l">unless-stopped</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">network_mode</span><span class="p">:</span><span class="w"> </span><span class="l">host</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">command</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s1">&#39;--bind.stats-url=http://127.0.0.1:8053/&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s1">&#39;--bind.stats-groups=server,view,tasks&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">volumes</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">prometheus_data</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">grafana_data</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">networks</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">monitoring</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">driver</span><span class="p">:</span><span class="w"> </span><span class="l">bridge</span><span class="w">
</span></span></span></code></pre></div><p>Keep the Grafana admin password out of the compose file. Put it in <code>.env</code> next to <code>docker-compose.yml</code> (mode 0600), which Docker Compose reads automatically:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nv">GRAFANA_ADMIN_PASSWORD</span><span class="o">=</span>change-me
</span></span></code></pre></div><p>Prometheus in the stack scrapes the exporter on the host and sends alerts to Alertmanager. Put the two rule files from the alerting sections in <code>prometheus/rules/</code>. The relabeling sets a fixed <code>instance</code> name, because <code>host.docker.internal</code> says nothing:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="c"># prometheus/prometheus.yml</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">global</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">scrape_interval</span><span class="p">:</span><span class="w"> </span><span class="l">15s</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">evaluation_interval</span><span class="p">:</span><span class="w"> </span><span class="l">15s</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">alerting</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">alertmanagers</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">static_configs</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span>- <span class="nt">targets</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s1">&#39;alertmanager:9093&#39;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">rule_files</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="l">/etc/prometheus/rules/*.yml</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">scrape_configs</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">job_name</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;prometheus&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">static_configs</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">targets</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s1">&#39;localhost:9090&#39;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">job_name</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;bind&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">static_configs</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">targets</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s1">&#39;host.docker.internal:9119&#39;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">relabel_configs</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">target_label</span><span class="p">:</span><span class="w"> </span><span class="l">instance</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">replacement</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;dns1&#39;</span><span class="w">
</span></span></span></code></pre></div><p>Alertmanager refuses to start without a configuration file. A minimal one sends every alert to a single receiver without notifications; add <code>email_configs</code>, <code>slack_configs</code> or <code>webhook_configs</code> to the receiver to get notified:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="c"># alertmanager/alertmanager.yml</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">route</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">receiver</span><span class="p">:</span><span class="w"> </span><span class="l">default</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">group_by</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s1">&#39;alertname&#39;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;instance&#39;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">receivers</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">default</span><span class="w">
</span></span></span></code></pre></div><p>Provision the Prometheus datasource so Grafana is ready to use on first start:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="c"># grafana/provisioning/datasources/prometheus.yml</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">apiVersion</span><span class="p">:</span><span class="w"> </span><span class="m">1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">datasources</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Prometheus</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">uid</span><span class="p">:</span><span class="w"> </span><span class="l">prometheus</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">type</span><span class="p">:</span><span class="w"> </span><span class="l">prometheus</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">access</span><span class="p">:</span><span class="w"> </span><span class="l">proxy</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">url</span><span class="p">:</span><span class="w"> </span><span class="l">http://prometheus:9090</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">isDefault</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span></code></pre></div><p>Start the stack and check that both targets are up:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">docker compose up -d
</span></span><span class="line"><span class="cl">curl -s http://localhost:9090/api/v1/targets <span class="p">|</span> grep -o <span class="s1">&#39;&#34;health&#34;:&#34;[a-z]*&#34;&#39;</span>
</span></span></code></pre></div><h2 id="security-monitoring">Security Monitoring <a class="anchor" data-pagefind-ignore href="#security-monitoring" aria-label="Link to this section">#</a></h2>
<h3 id="detecting-dns-attacks">Detecting DNS Attacks <a class="anchor" data-pagefind-ignore href="#detecting-dns-attacks" aria-label="Link to this section">#</a></h3>
<p>Traffic patterns reveal abuse before it becomes an outage. These rules go in <code>prometheus/rules/bind_security.yml</code>:</p>
<table>
	<thead>
			<tr>
					<th>Alert</th>
					<th>Fires when</th>
					<th>Possible cause</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>BindPossibleAmplificationAttack</code></td>
					<td>Over 100 ANY queries/s</td>
					<td>Your server used to amplify a DDoS</td>
			</tr>
			<tr>
					<td><code>BindHighNxdomainRate</code></td>
					<td>Over 30% NXDOMAIN for 10 minutes</td>
					<td>Enumeration, or malware generating random names</td>
			</tr>
			<tr>
					<td><code>BindQueryFlood</code></td>
					<td>Over 5000 queries/s</td>
					<td>Query flood</td>
			</tr>
	</tbody>
</table>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="c"># Security-focused alerts</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">groups</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">bind_security</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">rules</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="c"># Possible DNS amplification attack</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">alert</span><span class="p">:</span><span class="w"> </span><span class="l">BindPossibleAmplificationAttack</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">expr</span><span class="p">:</span><span class="w"> </span><span class="p">|</span><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">          sum(rate(bind_incoming_queries_total{type=&#34;ANY&#34;}[5m])) by (instance) &gt; 100</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">for</span><span class="p">:</span><span class="w"> </span><span class="l">2m</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">labels</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">severity</span><span class="p">:</span><span class="w"> </span><span class="l">critical</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">annotations</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">summary</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;Possible DNS amplification attack on {{ $labels.instance }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">description</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;High rate of ANY queries detected&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="c"># Unusual NXDOMAIN rate (possible enumeration)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">alert</span><span class="p">:</span><span class="w"> </span><span class="l">BindHighNxdomainRate</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">expr</span><span class="p">:</span><span class="w"> </span><span class="p">|</span><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">          sum(rate(bind_responses_total{result=&#34;NXDOMAIN&#34;}[5m])) by (instance) /
</span></span></span><span class="line"><span class="cl"><span class="sd">          sum(rate(bind_responses_total[5m])) by (instance) &gt; 0.3</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">for</span><span class="p">:</span><span class="w"> </span><span class="l">10m</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">labels</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">severity</span><span class="p">:</span><span class="w"> </span><span class="l">warning</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">annotations</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">summary</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;High NXDOMAIN rate on {{ $labels.instance }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">description</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;NXDOMAIN rate is {{ $value | humanizePercentage }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="c"># Query flood detection</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">alert</span><span class="p">:</span><span class="w"> </span><span class="l">BindQueryFlood</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">expr</span><span class="p">:</span><span class="w"> </span><span class="l">sum(rate(bind_incoming_queries_total[1m])) by (instance) &gt; 5000</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">for</span><span class="p">:</span><span class="w"> </span><span class="l">1m</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">labels</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">severity</span><span class="p">:</span><span class="w"> </span><span class="l">critical</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">annotations</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">summary</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;DNS query flood on {{ $labels.instance }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">description</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;Query rate: {{ $value }} q/s&#34;</span><span class="w">
</span></span></span></code></pre></div><h2 id="useful-promql-queries">Useful PromQL Queries <a class="anchor" data-pagefind-ignore href="#useful-promql-queries" aria-label="Link to this section">#</a></h2>
<h3 id="performance-analysis">Performance Analysis <a class="anchor" data-pagefind-ignore href="#performance-analysis" aria-label="Link to this section">#</a></h3>
<p>How long upstream queries take, and whether DNSSEC validation fails:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-promql" data-lang="promql"><span class="line"><span class="cl"><span class="c1"># 95th percentile upstream query latency</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="kr">histogram_quantile</span><span class="o">(</span><span class="mf">0.95</span><span class="p">,</span><span class="w"> </span><span class="k">sum</span><span class="o">(</span><span class="kr">rate</span><span class="o">(</span><span class="nv">bind_resolver_query_duration_seconds_bucket</span><span class="p">[</span><span class="s">5m</span><span class="p">]</span><span class="o">))</span><span class="w"> </span><span class="k">by</span><span class="w"> </span><span class="o">(</span><span class="nv">le</span><span class="o">))</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c1"># DNSSEC validation failures</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="kr">increase</span><span class="o">(</span><span class="nv">bind_resolver_dnssec_validation_errors_total</span><span class="p">[</span><span class="s">1h</span><span class="p">]</span><span class="o">)</span><span class="w">
</span></span></span></code></pre></div><p>Top queried domains come from the parsed query log, not from Prometheus. In Loki (LogQL):</p>
<pre tabindex="0"><code class="language-logql" data-lang="logql">topk(10, sum by (domain) (count_over_time({job=&#34;bind_queries&#34;}[1h])))
</code></pre><h3 id="capacity-planning">Capacity Planning <a class="anchor" data-pagefind-ignore href="#capacity-planning" aria-label="Link to this section">#</a></h3>
<p>Peak and daily volume tell you when to add a server; the cache size shows memory use growing:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-promql" data-lang="promql"><span class="line"><span class="cl"><span class="c1"># Peak query rate (last 7 days)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="kr">max_over_time</span><span class="o">(</span><span class="k">sum</span><span class="o">(</span><span class="kr">rate</span><span class="o">(</span><span class="nv">bind_incoming_queries_total</span><span class="p">[</span><span class="s">5m</span><span class="p">]</span><span class="o">))</span><span class="p">[</span><span class="s">7d</span><span class="err">:</span><span class="s">5m</span><span class="p">]</span><span class="o">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c1"># Average queries per day</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="k">sum</span><span class="o">(</span><span class="kr">increase</span><span class="o">(</span><span class="nv">bind_incoming_queries_total</span><span class="p">[</span><span class="s">24h</span><span class="p">]</span><span class="o">))</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c1"># Cache size (RRsets in cache)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="k">sum</span><span class="w"> </span><span class="k">by</span><span class="w"> </span><span class="o">(</span><span class="nv">instance</span><span class="o">)</span><span class="w"> </span><span class="o">(</span><span class="nv">bind_resolver_cache_rrsets</span><span class="o">)</span><span class="w">
</span></span></span></code></pre></div><h2 id="best-practices">Best Practices <a class="anchor" data-pagefind-ignore href="#best-practices" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Monitor all DNS servers</strong>: deploy bind_exporter on every BIND instance.</li>
<li><strong>Set appropriate scrape intervals</strong>: 15-30 seconds is usually sufficient.</li>
<li><strong>Retain metrics appropriately</strong>: keep high-resolution data for 15 days, aggregated data longer.</li>
<li><strong>Alert on trends, not spikes</strong>: use <code>for</code> duration to avoid alert fatigue.</li>
<li><strong>Correlate with other metrics</strong>: link DNS performance to application metrics.</li>
<li><strong>Document your dashboards</strong>: add descriptions to panels explaining what they show.</li>
<li><strong>Test your alerts</strong>: periodically verify alerts fire correctly.</li>
</ul>
<h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Statistics channel on localhost</strong>: it exposes server internals; keep <code>allow { localhost; }</code>.</li>
<li><strong>Firewall the exporter</strong>: port 9119 listens on all interfaces; only Prometheus needs it.</li>
<li><strong>Query logs are personal data</strong>: they show who looked up what. Limit access and retention.</li>
<li><strong>Grafana password in <code>.env</code></strong>: mode 0600, not in the compose file or Git.</li>
</ul>
<h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub: <a href="https://github.com/pderuiter/blog-bind-monitoring" rel="noopener">pderuiter/blog-bind-monitoring</a>. It creates an Ubuntu 24.04 VM on Proxmox and runs one playbook that enables the BIND statistics channel and query logging, and deploys this Docker Compose stack (or the systemd exporter); <code>tests/verify.yml</code> then checks bind_up, the Prometheus targets and rules, Alertmanager and the Grafana datasource.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>bind_exporter turns BIND&rsquo;s statistics channel into Prometheus metrics; Grafana shows them and Alertmanager tells you when something breaks.</p>
<p>This completes our BIND DNS series covering:</p>
<ol>
<li>Resolver configuration</li>
<li>Authoritative server setup</li>
<li>RNDC and remote management</li>
<li>Zone security and ACLs</li>
<li>Dynamic DNS updates</li>
<li>Catalog zones</li>
<li>DNSSEC validation</li>
<li>DNSSEC zone signing</li>
<li>Response Policy Zones</li>
<li>DNS over TLS</li>
<li>DNS over HTTPS</li>
<li>External-DNS integration</li>
<li>Prometheus monitoring</li>
</ol>
<p>With these building blocks, you can build a robust, secure, and observable DNS infrastructure for any environment - from homelab to enterprise.</p>
]]></content:encoded></item></channel></rss>