<?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>Encryption | A DevOps Blog</title><link>https://blog.bsdserver.nl/tag/encryption/</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/encryption/rss/" rel="self" type="application/rss+xml"/><ttl>60</ttl><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>Automatic Disk Decryption with Tang</title><link>https://blog.bsdserver.nl/automatic-disk-decryption-with-tang/</link><guid isPermaLink="false">693b4fc079eb54000160a43d</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Thu, 11 Dec 2025 23:12:00 +0000</pubDate><description>If you're setting up disk encryption on your Red Hat Enterprise Linux 9 (RHEL9) servers, using a Tang server can be a smart choice to streamline the…</description><category>Linux</category><category>Security</category><category>Ansible</category><category>RHEL</category><category>Encryption</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/linux-tang-disk-decryption.png" medium="image"/><content:encoded><![CDATA[<p>If you&rsquo;re setting up disk encryption on your Red Hat Enterprise Linux 9 (RHEL9) servers, every reboot asks for a passphrase. In a server farm that means someone at a console for each reboot, which makes automated restarts and patching impractical.</p>
<p>This post deploys a Tang server with Ansible and configures RHEL9 clients through Kickstart, so encrypted volumes unlock automatically at boot as long as the Tang server is reachable.</p>
<h2 id="why-tang">Why Tang? <a class="anchor" data-pagefind-ignore href="#why-tang" aria-label="Link to this section">#</a></h2>
<p>Encryption at rest keeps data unreadable when a disk or server is stolen. Tang removes the operational cost of it:</p>
<ul>
<li><strong>Unattended reboots</strong> - Clients unlock their LUKS volumes over the network, no passphrase typed.</li>
<li><strong>Location-bound unlocking</strong> - A disk only unlocks while it can reach your Tang server. Taken out of the network, it stays locked.</li>
<li><strong>Lightweight</strong> - Tang is a small HTTP service with nothing to manage per client.</li>
<li><strong>Repeatable</strong> - Ansible sets up the server, Kickstart sets up the clients, so every machine is configured the same way.</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 encrypted servers in a data centre or edge location that must reboot without someone typing a passphrase.</li>
<li><strong>Skip it</strong> for a single machine you reboot by hand, or a machine that is not on a trusted network at boot (a laptop). A passphrase or TPM is simpler there.</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>
<p>Tang works together with Clevis, the client-side tool that hooks into LUKS.</p>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Tang (<code>tangd.socket</code>)</td>
					<td>Tang server</td>
					<td>Answers Clevis requests over HTTP so the client can recover its key.</td>
			</tr>
			<tr>
					<td>Clevis + <code>clevis-dracut</code></td>
					<td>Each encrypted client</td>
					<td>Binds the LUKS volume to Tang and contacts Tang from the initramfs at boot.</td>
			</tr>
			<tr>
					<td>LUKS</td>
					<td>Each encrypted client</td>
					<td>The disk encryption itself. The original passphrase keeps working as a fallback.</td>
			</tr>
	</tbody>
</table>
<p>The flow: client boots → initramfs brings up the network → Clevis contacts Tang → the LUKS key is recovered → the volume unlocks → boot continues.</p>
<h2 id="prerequisites">Prerequisites <a class="anchor" data-pagefind-ignore href="#prerequisites" aria-label="Link to this section">#</a></h2>
<ol>
<li><strong>Red Hat Enterprise Linux 9 (RHEL9) Server</strong>: This tutorial assumes that you are using RHEL9. Make sure the system is installed and configured.</li>
<li><strong>Root or Sudo Access</strong>: You will need root privileges to install packages and configure services.</li>
<li><strong>Ansible Installed</strong>: Ansible should be installed on the control node to automate the deployment process.</li>
<li><strong>FirewallD Installed and Configured</strong>: The playbook assumes you are using FirewallD for managing firewall rules.</li>
<li><strong>Network Connectivity</strong>: Ensure that the Tang server and any client machines can communicate over the network.</li>
<li><strong>Clevis Installed on Clients</strong>: If you plan to use Tang to automate decryption, Clevis must be installed on the client systems.</li>
</ol>
<h2 id="deploying-the-tang-server-with-ansible">Deploying the Tang Server with Ansible <a class="anchor" data-pagefind-ignore href="#deploying-the-tang-server-with-ansible" aria-label="Link to this section">#</a></h2>
<p>Setting up Tang by hand is quick, but you want more than one Tang server for redundancy. A playbook keeps them identical.</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">hosts</span><span class="p">:</span><span class="w"> </span><span class="l">tang_server</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">become</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">tasks</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># Install packages required for Tang server</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">Install required packages for Tang server</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ansible.builtin.package</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></span><span class="line"><span class="cl"><span class="w">          </span>- <span class="l">tang</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- <span class="l">httpd</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">present</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"># Configure firewall rules for Tang server</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">Configure firewall for Tang server</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ansible.posix.firewalld</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">service</span><span class="p">:</span><span class="w"> </span><span class="l">http</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">permanent</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">enabled</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">immediate</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># Start and enable Tang server</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">Start and enable Tang server</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ansible.builtin.systemd</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">tangd.socket</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">enabled</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">started</span><span class="w">
</span></span></span></code></pre></div><p>What each task does:</p>
<ul>
<li><strong>Install packages</strong>: installs <code>tang</code> (and <code>httpd</code>).</li>
<li><strong>Firewall</strong>: Tang talks plain HTTP, so the <code>http</code> service (port 80) is opened. <code>immediate: true</code> applies the rule now as well as permanently, without a separate reload.</li>
<li><strong><code>tangd.socket</code></strong>: socket activation. systemd listens on the port and starts Tang per request; <code>enabled: true</code> makes it survive reboots.</li>
</ul>
<h2 id="configuring-the-clients-with-kickstart">Configuring the Clients with Kickstart <a class="anchor" data-pagefind-ignore href="#configuring-the-clients-with-kickstart" aria-label="Link to this section">#</a></h2>
<p>The client side is done at install time: encrypt the volume, install Clevis, and bind the volume to Tang.</p>
<h3 id="finding-the-luks-volume-uuid">Finding the LUKS Volume UUID <a class="anchor" data-pagefind-ignore href="#finding-the-luks-volume-uuid" aria-label="Link to this section">#</a></h3>
<p>You need to know which LUKS volume to bind. To look it up during the Kickstart installation:</p>
<ol>
<li><strong>Open a terminal</strong>: press <code>Ctrl+Alt+F2</code> during the installation.</li>
<li><strong>Find the partition</strong>: run <code>lsblk</code> and locate the encrypted device (e.g. <code>/dev/sda3</code>).</li>
<li><strong>Read its UUID</strong>:</li>
</ol>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo cryptsetup luksUUID /dev/sda3
</span></span></code></pre></div><p>Replace <code>/dev/sda3</code> with your device. The output is the <code>volume-UUID</code> of that LUKS partition, which identifies the volume in your Kickstart configuration.</p>
<h3 id="the-kickstart-snippet">The Kickstart Snippet <a class="anchor" data-pagefind-ignore href="#the-kickstart-snippet" aria-label="Link to this section">#</a></h3>
<p>This snippet installs Clevis, creates the encrypted volume and binds it to Tang in one installation run.</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 Clevis for client-side automation</span>
</span></span><span class="line"><span class="cl">%packages
</span></span><span class="line"><span class="cl">@core
</span></span><span class="line"><span class="cl">clevis
</span></span><span class="line"><span class="cl">clevis-dracut
</span></span><span class="line"><span class="cl">%end
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Partition and encrypt the logical volume</span>
</span></span><span class="line"><span class="cl">part pv.01 --size<span class="o">=</span><span class="m">1</span> --grow --encrypted --passphrase<span class="o">=</span>&lt;dummy-passphrase&gt;
</span></span><span class="line"><span class="cl">volgroup vg01 pv.01
</span></span><span class="line"><span class="cl">logvol / --fstype<span class="o">=</span><span class="s2">&#34;ext4&#34;</span> --name<span class="o">=</span>root --vgname<span class="o">=</span>vg01 --size<span class="o">=</span><span class="m">20480</span> --encrypted --passphrase<span class="o">=</span>&lt;dummy-passphrase&gt;
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Set up Clevis to use Tang for decryption</span>
</span></span><span class="line"><span class="cl">%post
</span></span><span class="line"><span class="cl"><span class="c1"># Bind the LUKS volume to Tang server for automatic decryption</span>
</span></span><span class="line"><span class="cl">clevis luks <span class="nb">bind</span> -d /dev/mapper/vg01-root tang <span class="s1">&#39;{&#34;url&#34;: &#34;http://&lt;Tang-server-IP&gt;:80&#34;}&#39;</span>
</span></span><span class="line"><span class="cl">%end
</span></span></code></pre></div><table>
	<thead>
			<tr>
					<th>Section</th>
					<th>What it does</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>%packages</code></td>
					<td><code>clevis</code> for binding, <code>clevis-dracut</code> so the initramfs can unlock at boot.</td>
			</tr>
			<tr>
					<td><code>part</code> / <code>volgroup</code> / <code>logvol</code></td>
					<td>Creates the encrypted volume with a temporary passphrase. Replace it after installation.</td>
			</tr>
			<tr>
					<td><code>%post</code></td>
					<td><code>clevis luks bind</code> adds a Tang-based key to the LUKS volume. From then on, boot unlocks it via Tang.</td>
			</tr>
	</tbody>
</table>
<h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Keep the passphrase.</strong> The <code>&lt;dummy-passphrase&gt;</code> stays a valid key. Change it to a strong one and store it safely; it is your fallback when Tang is unreachable.</li>
<li><strong>Tang reachable = disk unlockable.</strong> Anyone with the disk and network access to Tang can unlock it. Only expose Tang on the internal network where your servers boot.</li>
<li><strong>Run more than one Tang server.</strong> If the only Tang server is down, clients wait for the passphrase at boot.</li>
</ul>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>With a few lines of Ansible you have a Tang server, and with a Kickstart snippet every new client binds to it at install time. Encrypted servers can then reboot unattended, whether you run a handful or hundreds.</p>
<p>Give this Ansible playbook a try, and let me know how it works for you! If you have any questions or run into any challenges, feel free to leave a comment.</p>
]]></content:encoded></item></channel></rss>