<?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>Homelab | A DevOps Blog</title><link>https://blog.bsdserver.nl/tag/homelab/</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/tag/homelab/rss/" rel="self" type="application/rss+xml"/><ttl>60</ttl><item><title>Building Long-Term AI Memory with Qdrant and Claude's MCP Server</title><link>https://blog.bsdserver.nl/building-long-term-ai-memory-with-qdrant-and-claudes-mcp-server/</link><guid isPermaLink="false">69a8c55a3361030001c85baa</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Thu, 05 Mar 2026 01:16:23 +0000</pubDate><description>Ever wished your AI assistant could actually remember things between conversations?</description><category>Homelab</category><category>Automation</category><category>Docker</category><media:content url="https://blog.bsdserver.nl/content/images/2026/03/ai-memory-qdrant.png" medium="image"/><content:encoded><![CDATA[<p>Ever wished your AI assistant could actually <em>remember</em> things between conversations? Not just the current chat, but the architectural decisions you made three months ago, the patterns your team agreed on, or that obscure networking fix you discovered at 2 AM?</p>
<p>We built exactly that: a persistent, searchable long-term memory for Claude, with Qdrant as the vector database and the Model Context Protocol (MCP) as the glue. Think of it as a personal RAG (Retrieval-Augmented Generation) system that lives alongside your AI tooling. Here&rsquo;s how we set it up.</p>
<h2 id="why-long-term-memory">Why Long-Term Memory? <a class="anchor" data-pagefind-ignore href="#why-long-term-memory" aria-label="Link to this section">#</a></h2>
<p>When you&rsquo;re managing 70+ Terraform modules, 22 Ansible roles, a whole slew of playbooks, a sprawling Docker-based infrastructure and more than 180 pods on Kubernetes, you accumulate a <em>lot</em> of institutional knowledge quickly:</p>
<ul>
<li><strong>Architectural Decision Records (ADRs)</strong> - <em>why</em> you chose S3-compatible MinIO over Consul for Terraform state</li>
<li><strong>Naming conventions</strong> - <code>{tenant}-{env}-{type}-{role}{nnn}</code> and why that exact format</li>
<li><strong>Patterns that work</strong> - how to wire up Vault AppRole auth across all your modules</li>
<li><strong>Patterns that <em>don&rsquo;t</em> work</strong> - the time you tried <code>force_path_style</code> with the new AWS provider and spent half a day debugging</li>
</ul>
<p>Without long-term memory, every new conversation with Claude starts from zero. You re-explain context and watch Claude suggest approaches you&rsquo;ve already rejected. With Qdrant-backed memory, Claude recalls all of this through semantic search.</p>
<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 work with Claude daily on the same infrastructure and keep repeating the same context.</li>
<li><strong>Skip it</strong> for occasional, unrelated questions. A short <code>CLAUDE.md</code> or project notes file is simpler when the context fits on one page.</li>
</ul>
<h2 id="architecture-overview">Architecture Overview <a class="anchor" data-pagefind-ignore href="#architecture-overview" aria-label="Link to this section">#</a></h2>
<p><img src="https://blog.bsdserver.nl/content/images/2026/03/qdrant-mcp-architecture.drawio-1_hu_d125a5efea255cee.webp" srcset="https://blog.bsdserver.nl/content/images/2026/03/qdrant-mcp-architecture.drawio-1_hu_522457908f5a3550.webp 480w, /content/images/2026/03/qdrant-mcp-architecture.drawio-1_hu_d125a5efea255cee.webp 800w" sizes="(min-width: 760px) 720px, 100vw" width="800" height="158" alt="" class="post-image" loading="lazy" decoding="async"></p>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Qdrant</td>
					<td>A server, here <code>qdrant.bsdserver.nl</code> (Docker)</td>
					<td>Open-source vector database. Stores the memories as vectors plus their text.</td>
			</tr>
			<tr>
					<td>mcp-server-qdrant</td>
					<td>Your workstation, started by Claude</td>
					<td>The official Qdrant MCP server. Embeds text and exposes <code>store</code> and <code>find</code> tools to Claude.</td>
			</tr>
			<tr>
					<td>Claude (CLI or Desktop)</td>
					<td>Your workstation</td>
					<td>Calls the tools when you ask it to remember or recall something.</td>
			</tr>
	</tbody>
</table>
<p>The flow: you ask Claude to remember something → Claude calls the store tool → the MCP server embeds the text with a sentence transformer model → the vector and text go into Qdrant. Recall runs the same way: the question is embedded and Qdrant returns the most similar entries.</p>
<h2 id="step-1-deploy-qdrant">Step 1: Deploy Qdrant <a class="anchor" data-pagefind-ignore href="#step-1-deploy-qdrant" aria-label="Link to this section">#</a></h2>
<p>Qdrant is the only server-side part. We run it as a Docker container:</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">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">qdrant</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">qdrant/qdrant:latest</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">qdrant</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">always</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;6333:6333&#34;</span><span class="w">   </span><span class="c"># REST API</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s2">&#34;6334:6334&#34;</span><span class="w">   </span><span class="c"># gRPC</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">qdrant_data:/qdrant/storage</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">QDRANT__SERVICE__API_KEY=your-secure-api-key-here</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">QDRANT__SERVICE__ENABLE_TLS=false</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">qdrant_data</span><span class="p">:</span><span class="w">
</span></span></span></code></pre></div><ul>
<li><code>qdrant_data</code> volume: the stored memories. Back it up.</li>
<li><code>QDRANT__SERVICE__API_KEY</code>: every client must send this key. It is the only access control here.</li>
<li><code>ENABLE_TLS=false</code>: in our case Qdrant sits behind a reverse proxy (Traefik) that handles TLS termination, so the service itself doesn&rsquo;t need TLS.</li>
</ul>
<p>After starting the container, verify it&rsquo;s healthy:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">curl https://qdrant.bsdserver.nl/healthz
</span></span><span class="line"><span class="cl"><span class="c1"># Returns: healthz check passed</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">curl https://qdrant.bsdserver.nl/
</span></span><span class="line"><span class="cl"><span class="c1"># Returns: {&#34;title&#34;:&#34;qdrant - vector search engine&#34;,&#34;version&#34;:&#34;...&#34;}</span>
</span></span></code></pre></div><p>You don&rsquo;t need to create collections upfront. The MCP server creates them on first use.</p>
<h2 id="step-2-install-the-mcp-server">Step 2: Install the MCP Server <a class="anchor" data-pagefind-ignore href="#step-2-install-the-mcp-server" aria-label="Link to this section">#</a></h2>
<p><code>mcp-server-qdrant</code> is a Python package on PyPI. Run it with <code>uvx</code> (part of the <code>uv</code> Python package manager), which downloads it into an isolated environment, so there is no separate installation step:</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 it manually first</span>
</span></span><span class="line"><span class="cl">uvx mcp-server-qdrant
</span></span></code></pre></div><h2 id="step-3-configure-claude">Step 3: Configure Claude <a class="anchor" data-pagefind-ignore href="#step-3-configure-claude" aria-label="Link to this section">#</a></h2>
<p>Claude starts the MCP server itself and passes it the connection settings as environment variables.</p>
<h3 id="for-claude-code-cli">For Claude Code (CLI) <a class="anchor" data-pagefind-ignore href="#for-claude-code-cli" aria-label="Link to this section">#</a></h3>
<p>Register the server with <code>claude mcp add</code>. MCP servers aren&rsquo;t configured in <code>.claude/settings.local.json</code>; the CLI writes them to <code>~/.claude.json</code> (scopes <code>local</code> and <code>user</code>) or to <code>.mcp.json</code> in the project (scope <code>project</code>). Pass the environment variables with <code>-e</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">claude mcp add qdrant-memory <span class="se">\
</span></span></span><span class="line"><span class="cl">  --transport stdio <span class="se">\
</span></span></span><span class="line"><span class="cl">  -e <span class="nv">QDRANT_URL</span><span class="o">=</span>https://qdrant.bsdserver.nl:443 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -e <span class="nv">QDRANT_API_KEY</span><span class="o">=</span>your-api-key-here <span class="se">\
</span></span></span><span class="line"><span class="cl">  -e <span class="nv">COLLECTION_NAME</span><span class="o">=</span>architectural-decisions <span class="se">\
</span></span></span><span class="line"><span class="cl">  -e <span class="nv">EMBEDDING_MODEL</span><span class="o">=</span>sentence-transformers/all-MiniLM-L6-v2 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -- uvx mcp-server-qdrant
</span></span></code></pre></div><table>
	<thead>
			<tr>
					<th>Variable</th>
					<th>What it does</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>QDRANT_URL</code></td>
					<td>Where Qdrant runs (here via the TLS proxy on 443).</td>
			</tr>
			<tr>
					<td><code>QDRANT_API_KEY</code></td>
					<td>The key from the Compose file.</td>
			</tr>
			<tr>
					<td><code>COLLECTION_NAME</code></td>
					<td>Which collection holds the memories (see Step 4).</td>
			</tr>
			<tr>
					<td><code>EMBEDDING_MODEL</code></td>
					<td>Which model turns text into vectors (see Step 5).</td>
			</tr>
	</tbody>
</table>
<p>The resulting entry looks like this (you can also write it by hand in <code>.mcp.json</code>):</p>
<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;mcpServers&#34;</span><span class="p">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="nt">&#34;qdrant-memory&#34;</span><span class="p">:</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;stdio&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;command&#34;</span><span class="p">:</span> <span class="s2">&#34;uvx&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;args&#34;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&#34;mcp-server-qdrant&#34;</span><span class="p">],</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;env&#34;</span><span class="p">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="nt">&#34;QDRANT_URL&#34;</span><span class="p">:</span> <span class="s2">&#34;https://qdrant.bsdserver.nl:443&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="nt">&#34;QDRANT_API_KEY&#34;</span><span class="p">:</span> <span class="s2">&#34;your-api-key-here&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="nt">&#34;COLLECTION_NAME&#34;</span><span class="p">:</span> <span class="s2">&#34;architectural-decisions&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="nt">&#34;EMBEDDING_MODEL&#34;</span><span class="p">:</span> <span class="s2">&#34;sentence-transformers/all-MiniLM-L6-v2&#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 class="p">}</span>
</span></span></code></pre></div><h3 id="for-claude-desktop">For Claude Desktop <a class="anchor" data-pagefind-ignore href="#for-claude-desktop" aria-label="Link to this section">#</a></h3>
<p>Add the same configuration to <code>~/Library/Application Support/Claude/claude_desktop_config.json</code> (macOS) or the equivalent path on your OS.</p>
<h2 id="step-4-choose-your-collection-strategy">Step 4: Choose Your Collection Strategy <a class="anchor" data-pagefind-ignore href="#step-4-choose-your-collection-strategy" aria-label="Link to this section">#</a></h2>
<p><code>COLLECTION_NAME</code> decides which Qdrant collection stores your memories. Collections work like namespaces:</p>
<table>
	<thead>
			<tr>
					<th>Collection</th>
					<th>Purpose</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>architectural-decisions</code></td>
					<td>ADRs, design choices, patterns</td>
			</tr>
			<tr>
					<td><code>runbooks</code></td>
					<td>Operational procedures, incident responses</td>
			</tr>
			<tr>
					<td><code>project-notes</code></td>
					<td>Meeting notes, sprint decisions</td>
			</tr>
	</tbody>
</table>
<p>We started with a single <code>architectural-decisions</code> collection that stores everything from Terraform backend standardization decisions to Ansible role conventions. You can always split later.</p>
<h2 id="step-5-choose-your-embedding-model">Step 5: Choose Your Embedding Model <a class="anchor" data-pagefind-ignore href="#step-5-choose-your-embedding-model" aria-label="Link to this section">#</a></h2>
<p><code>EMBEDDING_MODEL</code> determines how text gets converted to vectors. The MCP server embeds with FastEmbed, so only models FastEmbed supports work.</p>
<table>
	<thead>
			<tr>
					<th>Model</th>
					<th>Size</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>sentence-transformers/all-MiniLM-L6-v2</code></td>
					<td>~80MB, 384 dimensions</td>
					<td>The default choice: small, fast, runs locally without a GPU, good on technical text. Downloaded automatically from HuggingFace on first use.</td>
			</tr>
			<tr>
					<td><code>sentence-transformers/paraphrase-multilingual-mpnet-base-v2</code></td>
					<td>~1GB, 768 dimensions</td>
					<td>Larger knowledge bases or more nuanced retrieval.</td>
			</tr>
	</tbody>
</table>
<ul>
<li><code>all-mpnet-base-v2</code> isn&rsquo;t supported: the server refuses to start with <code>Model sentence-transformers/all-mpnet-base-v2 is not supported in TextEmbedding</code>.</li>
<li>A collection is tied to the vector size of the model that created it, so switching models means a new collection.</li>
</ul>
<h2 id="step-6-start-storing-knowledge">Step 6: Start Storing Knowledge <a class="anchor" data-pagefind-ignore href="#step-6-start-storing-knowledge" aria-label="Link to this section">#</a></h2>
<p>Once configured, Claude gains two new tools:</p>
<ul>
<li><strong><code>qdrant-store</code></strong> - Store a piece of information with metadata</li>
<li><strong><code>qdrant-find</code></strong> - Semantically search stored information</li>
</ul>
<p>You can store knowledge conversationally:</p>
<blockquote>
<p>&ldquo;Remember that we standardized all Terraform modules to use empty <code>backend &quot;s3&quot; {}</code> blocks with runtime <code>-backend-config</code> flags, replacing the old inline endpoint configuration.&rdquo;</p>
</blockquote>
<p>Claude uses <code>qdrant-store</code> to persist this. Behind the scenes:</p>
<ol>
<li>The text is embedded into a 384-dimensional vector using the sentence transformer</li>
<li>The vector + original text + metadata are stored in the Qdrant collection</li>
<li>A unique ID is generated for later retrieval</li>
</ol>
<h2 id="step-7-retrieve-knowledge">Step 7: Retrieve Knowledge <a class="anchor" data-pagefind-ignore href="#step-7-retrieve-knowledge" aria-label="Link to this section">#</a></h2>
<p>In future conversations, Claude can search your knowledge base semantically:</p>
<blockquote>
<p>&ldquo;How do we handle Terraform state backend configuration?&rdquo;</p>
</blockquote>
<p>Claude uses <code>qdrant-find</code>, and Qdrant returns the most similar entries even if the exact words don&rsquo;t match. &ldquo;State backend configuration&rdquo; finds the note about &ldquo;empty backend blocks with runtime -backend-config flags&rdquo;: meaning matters more than exact wording.</p>
<h3 id="in-practice">In Practice <a class="anchor" data-pagefind-ignore href="#in-practice" aria-label="Link to this section">#</a></h3>
<p>We stored an architectural decision about Vault authentication:</p>
<blockquote>
<p>&ldquo;All Terraform modules must use AppRole authentication with Vault. The role_id and secret_id are injected via CI/CD pipeline variables, never hardcoded. The toolkit&rsquo;s _vault.sh library handles authentication automatically.&rdquo;</p>
</blockquote>
<p>Weeks later, working on a new module, we asked Claude:</p>
<blockquote>
<p>&ldquo;How should this module authenticate to Vault?&rdquo;</p>
</blockquote>
<p>Claude searched the vector DB, found the decision, and applied it correctly without us re-explaining the pattern.</p>
<h2 id="production-tips">Production Tips <a class="anchor" data-pagefind-ignore href="#production-tips" aria-label="Link to this section">#</a></h2>
<p>What you store decides what you get back:</p>
<table>
	<thead>
			<tr>
					<th>Tip</th>
					<th>Instead of</th>
					<th>Store</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><strong>Be specific</strong></td>
					<td>&ldquo;we use Vault&rdquo;</td>
					<td>&ldquo;We authenticate to Vault using AppRole method. The CI/CD pipeline injects VAULT_ROLE_ID and VAULT_SECRET_ID as environment variables. The toolkit&rsquo;s _vault.sh library handles the auth flow.&rdquo;</td>
			</tr>
			<tr>
					<td><strong>Include the <em>why</em></strong></td>
					<td>&ldquo;we use MinIO for state&rdquo;</td>
					<td>&ldquo;We chose MinIO over Consul for Terraform state because MinIO provides S3-compatible API, supports versioning for state file history, and integrates with our existing backup infrastructure&rdquo;</td>
			</tr>
			<tr>
					<td><strong>Store negative decisions</strong></td>
					<td>nothing</td>
					<td>&ldquo;We evaluated Terraform Cloud but rejected it because our air-gapped environments can&rsquo;t reach HashiCorp&rsquo;s SaaS, and self-hosted Terraform Enterprise licensing was prohibitive for our scale&rdquo;</td>
			</tr>
	</tbody>
</table>
<ul>
<li><strong>Review and prune periodically.</strong> Outdated decisions create confusion. If you&rsquo;ve migrated from <code>force_path_style</code> to <code>use_path_style</code>, update the stored memory.</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>The API key is full access.</strong> It reads and writes all memories. Treat it like any other credential, rotate it periodically and don&rsquo;t commit it to version control.</li>
<li><strong>The key is in your MCP config.</strong> <code>~/.claude.json</code> and <code>.mcp.json</code> contain it in plain text; don&rsquo;t commit a <code>.mcp.json</code> with a real key.</li>
<li><strong>Put TLS in front.</strong> Qdrant runs without TLS here; the reverse proxy provides it.</li>
</ul>
<h2 id="the-bigger-picture">The Bigger Picture <a class="anchor" data-pagefind-ignore href="#the-bigger-picture" aria-label="Link to this section">#</a></h2>
<p>This Qdrant + MCP setup is one piece of our broader AI-augmented infrastructure stack:</p>
<ul>
<li><strong>Qdrant</strong> for long-term memory (architectural decisions, patterns)</li>
<li><strong>Gitea MCP</strong> for direct repository access</li>
<li><strong>Vault MCP</strong> for secrets management</li>
<li><strong>Docker MCP</strong> for container operations</li>
<li><strong>n8n MCP</strong> for workflow automation</li>
<li><strong>Ansible MCP</strong> for infrastructure automation</li>
<li><strong>Terraform MCP</strong> for IaC code</li>
</ul>
<p>Each MCP server gives Claude domain-specific capabilities; the vector database adds persistent memory of <em>your</em> infrastructure, with its decisions, conventions and hard-won lessons.</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-qdrant-mcp" rel="noopener">pderuiter/blog-qdrant-mcp</a>. It creates an Ubuntu 24.04 VM, runs Qdrant with an API key on Docker, and registers the MCP server with <code>claude mcp add</code> on your workstation. Run <code>terraform apply</code>, then <code>ansible-playbook site.yml</code>.</p>
<h2 id="wrapping-up">Wrapping Up <a class="anchor" data-pagefind-ignore href="#wrapping-up" aria-label="Link to this section">#</a></h2>
<p>Setting up long-term AI memory with Qdrant took us about 30 minutes: deploy a container, configure an MCP server, and start storing. From then on every decision, debugging insight and convention is retrievable in plain language.</p>
<p>If you find yourself repeatedly explaining the same context to AI tools, a vector database-backed memory is one of the highest-leverage improvements you can make.</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><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>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>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></channel></rss>