<?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>nginx | A DevOps Blog</title><link>https://blog.bsdserver.nl/tag/nginx/</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/nginx/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></channel></rss>