<?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>HTTPS | A DevOps Blog</title><link>https://blog.bsdserver.nl/tag/https/</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/https/rss/" rel="self" type="application/rss+xml"/><ttl>60</ttl><item><title>HAProxy with Let's Encrypt: Automated HTTPS Certificate Management</title><link>https://blog.bsdserver.nl/haproxy-with-lets-encrypt-automated-https-certificate-management/</link><guid isPermaLink="false">693b734379eb54000160a5f2</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:43:31 +0000</pubDate><description>HTTPS is no longer optional - it's a requirement for modern web applications.</description><category>HAProxy</category><category>Let's Encrypt</category><category>HTTPS</category><category>TLS</category><category>Certificates</category><category>Security</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/haproxy-letsencrypt-certificates.png" medium="image"/><content:encoded><![CDATA[<p>HTTPS is no longer optional - it&rsquo;s a requirement for modern web applications. Let&rsquo;s Encrypt certificates are free but expire after 90 days, so renewing and installing them by hand does not scale.</p>
<p>This guide connects HAProxy to certbot: HAProxy terminates TLS and routes the ACME challenge, certbot obtains and renews the certificates, and a deploy hook loads renewed certificates into HAProxy, without a restart where possible.</p>
<h2 id="why-lets-encrypt-with-haproxy">Why Let&rsquo;s Encrypt with HAProxy? <a class="anchor" data-pagefind-ignore href="#why-lets-encrypt-with-haproxy" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Free, trusted certificates</strong> for every domain behind the load balancer</li>
<li><strong>One place for TLS</strong>: backends speak plain HTTP, certificates live only on HAProxy</li>
<li><strong>Automatic renewal</strong> with a systemd timer or cron</li>
<li><strong>No downtime</strong>: the runtime API swaps certificates in a running HAProxy</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> for public sites where HAProxy is the TLS endpoint and is reachable from the internet (HTTP-01) or your DNS has an API (DNS-01).</li>
<li><strong>Skip it</strong> for internal services without public DNS (use an internal CA), or when backends must terminate TLS themselves (TLS passthrough).</li>
</ul>
<h2 id="architecture-overview">Architecture Overview <a class="anchor" data-pagefind-ignore href="#architecture-overview" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>HAProxy</td>
					<td>Load balancer</td>
					<td>Terminates TLS with the PEM files in <code>/etc/haproxy/certs/</code>; sends <code>/.well-known/acme-challenge/</code> on port 80 to the challenge server.</td>
			</tr>
			<tr>
					<td>Challenge server</td>
					<td>Load balancer, <code>127.0.0.1:8080</code> (8888 in Method 1)</td>
					<td>Serves the webroot where certbot writes challenge files.</td>
			</tr>
			<tr>
					<td>Certbot</td>
					<td>Load balancer</td>
					<td>Requests and renews certificates in <code>/etc/letsencrypt/live/&lt;name&gt;/</code>.</td>
			</tr>
			<tr>
					<td>Deploy hook</td>
					<td>Load balancer</td>
					<td>Combines <code>fullchain.pem</code> and <code>privkey.pem</code>, loads the result into HAProxy.</td>
			</tr>
	</tbody>
</table>
<p>The flow: certbot writes a challenge file → Let&rsquo;s Encrypt fetches it over HTTP → HAProxy routes it to the challenge server → certificate issued → deploy hook builds the PEM → runtime API updates HAProxy.</p>
<h3 id="choosing-a-method">Choosing a method <a class="anchor" data-pagefind-ignore href="#choosing-a-method" aria-label="Link to this section">#</a></h3>
<table>
	<thead>
			<tr>
					<th>Method</th>
					<th>HAProxy downtime</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>1. HTTP-01 webroot</td>
					<td>None</td>
					<td>The basic setup behind HAProxy</td>
			</tr>
			<tr>
					<td>2. Standalone with hooks</td>
					<td>Seconds per renewal</td>
					<td>Simple setups where a short stop is acceptable</td>
			</tr>
			<tr>
					<td>3. Runtime API</td>
					<td>None, no reload</td>
					<td>Production (recommended)</td>
			</tr>
			<tr>
					<td>4. DNS-01</td>
					<td>None</td>
					<td>Wildcard certificates, servers not reachable on port 80</td>
			</tr>
	</tbody>
</table>
<h2 id="prerequisites">Prerequisites <a class="anchor" data-pagefind-ignore href="#prerequisites" aria-label="Link to this section">#</a></h2>
<ul>
<li>HAProxy from the official packages (examples checked on 3.4 LTS and on 3.3, the newest branch for Ubuntu 24.04)</li>
<li>Certbot installed</li>
<li>Domain(s) pointing to your HAProxy server</li>
<li>Port 80 and 443 accessible from the internet</li>
</ul>
<h2 id="installation">Installation <a class="anchor" data-pagefind-ignore href="#installation" aria-label="Link to this section">#</a></h2>
<h3 id="install-haproxy">Install HAProxy <a class="anchor" data-pagefind-ignore href="#install-haproxy" aria-label="Link to this section">#</a></h3>
<p>The runtime certificate API used in Method 3 needs HAProxy 2.4 or later. Use the official packages from <a href="https://haproxy.debian.net" rel="noopener">haproxy.debian.net</a> rather than the distribution package:</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"># Ubuntu 24.04: official PPA. 3.3 is the newest branch built for 24.04; it is a</span>
</span></span><span class="line"><span class="cl"><span class="c1"># short-lived, non-LTS branch. HAProxy 3.4 LTS is available for Ubuntu 26.04</span>
</span></span><span class="line"><span class="cl"><span class="c1"># (ppa:vbernat/haproxy-3.4) and for Debian 13 (below).</span>
</span></span><span class="line"><span class="cl">apt update
</span></span><span class="line"><span class="cl">apt install --no-install-recommends software-properties-common
</span></span><span class="line"><span class="cl">add-apt-repository ppa:vbernat/haproxy-3.3
</span></span><span class="line"><span class="cl">apt install <span class="nv">haproxy</span><span class="o">=</span>3.3.<span class="se">\*</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Debian 13: official haproxy.debian.net repository (3.4 LTS)</span>
</span></span><span class="line"><span class="cl">curl https://haproxy.debian.net/haproxy-archive-keyring.gpg <span class="se">\
</span></span></span><span class="line"><span class="cl">  --create-dirs --output /etc/apt/keyrings/haproxy-archive-keyring.gpg
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> deb <span class="s2">&#34;[signed-by=/etc/apt/keyrings/haproxy-archive-keyring.gpg]&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  https://haproxy.debian.net trixie-backports-3.4 main <span class="se">\
</span></span></span><span class="line"><span class="cl">  &gt; /etc/apt/sources.list.d/haproxy.list
</span></span><span class="line"><span class="cl">apt update
</span></span><span class="line"><span class="cl">apt install <span class="nv">haproxy</span><span class="o">=</span>3.4.<span class="se">\*</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># RHEL/CentOS (no official repository: AppStream ships 2.8)</span>
</span></span><span class="line"><span class="cl">yum install haproxy
</span></span><span class="line"><span class="cl"><span class="c1"># RHEL only: the unit does not create /run/haproxy, which the admin socket below needs</span>
</span></span><span class="line"><span class="cl">mkdir -p /etc/systemd/system/haproxy.service.d
</span></span><span class="line"><span class="cl"><span class="nb">printf</span> <span class="s1">&#39;[Service]\nRuntimeDirectory=haproxy\n&#39;</span> &gt; /etc/systemd/system/haproxy.service.d/runtime-directory.conf
</span></span><span class="line"><span class="cl">systemctl daemon-reload
</span></span></code></pre></div><h3 id="install-certbot">Install Certbot <a class="anchor" data-pagefind-ignore href="#install-certbot" aria-label="Link to this section">#</a></h3>
<p>Certbot is the Let&rsquo;s Encrypt client. Pick one source; the snap gets updates first.</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"># Debian/Ubuntu</span>
</span></span><span class="line"><span class="cl">apt install certbot
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># RHEL/CentOS (certbot comes from EPEL)</span>
</span></span><span class="line"><span class="cl">yum install epel-release
</span></span><span class="line"><span class="cl">yum install certbot
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Or using snap (recommended by Let&#39;s Encrypt)</span>
</span></span><span class="line"><span class="cl">snap install --classic certbot
</span></span><span class="line"><span class="cl">ln -s /snap/bin/certbot /usr/bin/certbot
</span></span></code></pre></div><h2 id="haproxy-certificate-format">HAProxy Certificate Format <a class="anchor" data-pagefind-ignore href="#haproxy-certificate-format" aria-label="Link to this section">#</a></h2>
<p>HAProxy requires certificates in a specific format: the certificate chain and private key combined in a single PEM file.</p>
<pre tabindex="0"><code>-----BEGIN CERTIFICATE-----
[Your domain certificate]
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
[Intermediate certificate]
-----END CERTIFICATE-----
-----BEGIN PRIVATE KEY-----
[Private key]
-----END PRIVATE KEY-----
</code></pre><p>Let&rsquo;s Encrypt provides separate files (<code>fullchain.pem</code>, <code>privkey.pem</code>), so every method below combines them. Repeat this after each renewal, or HAProxy keeps serving the old certificate.</p>
<h2 id="method-1-http-01-challenge-with-haproxy">Method 1: HTTP-01 Challenge with HAProxy <a class="anchor" data-pagefind-ignore href="#method-1-http-01-challenge-with-haproxy" aria-label="Link to this section">#</a></h2>
<p>Let&rsquo;s Encrypt checks that you control a domain by fetching a token from <code>http://&lt;domain&gt;/.well-known/acme-challenge/</code> on port 80. HAProxy already owns port 80, so it routes that path to a small local web server and redirects everything else to HTTPS.</p>
<h3 id="haproxy-configuration">HAProxy Configuration <a class="anchor" data-pagefind-ignore href="#haproxy-configuration" aria-label="Link to this section">#</a></h3>
<ul>
<li><code>acl is_acme_challenge</code>: matches the challenge path; <code>use_backend</code> sends it to <code>127.0.0.1:8888</code>.</li>
<li><code>redirect scheme https unless is_acme_challenge</code>: all other HTTP goes to HTTPS. The challenge must stay on HTTP.</li>
<li><code>crt /etc/haproxy/certs/</code>: loads every PEM in the directory; HAProxy picks one by SNI.</li>
<li><code>Strict-Transport-Security</code>: tells browsers to use HTTPS only. <code>preload</code> and <code>includeSubDomains</code> are hard to undo, so add them only when every subdomain has HTTPS.</li>
</ul>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy"># /etc/haproxy/haproxy.cfg

global
    log /dev/log local0
    chroot /var/lib/haproxy
    stats socket /run/haproxy/admin.sock mode 660 level admin
    user haproxy
    group haproxy
    daemon
    
    # SSL/TLS settings
    ssl-default-bind-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384
    ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
    ssl-default-bind-options ssl-min-ver TLSv1.2 no-tls-tickets
    tune.ssl.default-dh-param 2048

defaults
    log global
    mode http
    option httplog
    option dontlognull
    timeout connect 5s
    timeout client  50s
    timeout server  50s

# HTTP Frontend - handles Let&#39;s Encrypt challenges and redirects
frontend http_frontend
    bind *:80
    
    # Let&#39;s Encrypt ACME challenge
    acl is_acme_challenge path_beg /.well-known/acme-challenge/
    use_backend letsencrypt_backend if is_acme_challenge
    
    # Redirect all other HTTP to HTTPS
    http-request redirect scheme https unless is_acme_challenge

# HTTPS Frontend
frontend https_frontend
    bind *:443 ssl crt /etc/haproxy/certs/ alpn h2,http/1.1
    
    # HSTS header
    http-response set-header Strict-Transport-Security &#34;max-age=31536000; includeSubDomains; preload&#34;
    
    # Default backend
    default_backend web_servers

# Backend for Let&#39;s Encrypt challenges
backend letsencrypt_backend
    server certbot 127.0.0.1:8888

# Your web servers
backend web_servers
    balance roundrobin
    server web1 192.168.1.10:8080 check
    server web2 192.168.1.11:8080 check
</code></pre><h3 id="initial-certificate-request">Initial Certificate Request <a class="anchor" data-pagefind-ignore href="#initial-certificate-request" aria-label="Link to this section">#</a></h3>
<p>HAProxy does not start with an empty certificate directory, so the first certificate comes from certbot&rsquo;s standalone mode: certbot runs its own web server on port 80 while HAProxy is stopped.</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"># Stop HAProxy temporarily</span>
</span></span><span class="line"><span class="cl">systemctl stop haproxy
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Get initial certificate</span>
</span></span><span class="line"><span class="cl">certbot certonly --standalone <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d example.com <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d www.example.com <span class="se">\
</span></span></span><span class="line"><span class="cl">  --email admin@example.com <span class="se">\
</span></span></span><span class="line"><span class="cl">  --agree-tos <span class="se">\
</span></span></span><span class="line"><span class="cl">  --non-interactive
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Combine certificate files for HAProxy</span>
</span></span><span class="line"><span class="cl">mkdir -p /etc/haproxy/certs
</span></span><span class="line"><span class="cl"><span class="nv">BASE_DIR</span><span class="o">=</span>/etc/letsencrypt/live/example.com
</span></span><span class="line"><span class="cl">cat <span class="nv">$BASE_DIR</span>/fullchain.pem <span class="nv">$BASE_DIR</span>/privkey.pem &gt; /etc/haproxy/certs/example.com.pem
</span></span><span class="line"><span class="cl">chmod <span class="m">600</span> /etc/haproxy/certs/example.com.pem
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Start HAProxy</span>
</span></span><span class="line"><span class="cl">systemctl start haproxy
</span></span></code></pre></div><h3 id="renewal-with-http-01-challenge">Renewal with HTTP-01 Challenge <a class="anchor" data-pagefind-ignore href="#renewal-with-http-01-challenge" aria-label="Link to this section">#</a></h3>
<p>Once HAProxy is running, use webroot mode for renewals: certbot writes the token into a directory, and a web server on port 8888 serves it to HAProxy&rsquo;s ACME backend.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Create directory for challenges</span>
</span></span><span class="line"><span class="cl">mkdir -p /var/www/letsencrypt/.well-known/acme-challenge
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Use a simple HTTP server for challenges</span>
</span></span><span class="line"><span class="cl"><span class="c1"># Option 1: Python</span>
</span></span><span class="line"><span class="cl"><span class="nb">cd</span> /var/www/letsencrypt <span class="o">&amp;&amp;</span> python3 -m http.server <span class="m">8888</span> <span class="p">&amp;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Option 2: socat (install socat package)</span>
</span></span><span class="line"><span class="cl"><span class="c1"># Create a script to serve files</span>
</span></span></code></pre></div><p>Then point certbot at the webroot. Method 3 replaces the background Python process with a systemd service.</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"># For a certificate that already exists, add --force-renewal (otherwise certbot asks interactively)</span>
</span></span><span class="line"><span class="cl">certbot certonly --webroot <span class="se">\
</span></span></span><span class="line"><span class="cl">  -w /var/www/letsencrypt <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d example.com <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d www.example.com
</span></span></code></pre></div><h2 id="method-2-using-certbot-standalone-with-haproxy">Method 2: Using Certbot Standalone with HAProxy <a class="anchor" data-pagefind-ignore href="#method-2-using-certbot-standalone-with-haproxy" aria-label="Link to this section">#</a></h2>
<p>This method temporarily stops HAProxy during renewal, so certbot&rsquo;s standalone server can use port 80. Simple, but the site is down for a few seconds per renewal.</p>
<h3 id="pre-and-post-hooks">Pre and Post Hooks <a class="anchor" data-pagefind-ignore href="#pre-and-post-hooks" aria-label="Link to this section">#</a></h3>
<p>Certbot runs <code>pre-hook</code> before and <code>post-hook</code> after each renewal attempt.</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"># /etc/letsencrypt/cli.ini</span>
</span></span><span class="line"><span class="cl"><span class="c1"># cli.ini has no sections: these hooks apply to every certbot run.</span>
</span></span><span class="line"><span class="cl"><span class="c1"># Only use this for certificates obtained with --standalone; webroot</span>
</span></span><span class="line"><span class="cl"><span class="c1"># renewals fail while HAProxy is stopped.</span>
</span></span><span class="line"><span class="cl">pre-hook <span class="o">=</span> systemctl stop haproxy
</span></span><span class="line"><span class="cl">post-hook <span class="o">=</span> /etc/letsencrypt/renewal-hooks/deploy/haproxy.sh
</span></span></code></pre></div><h3 id="deployment-script">Deployment Script <a class="anchor" data-pagefind-ignore href="#deployment-script" aria-label="Link to this section">#</a></h3>
<p>Combines the renewed files for each domain and brings HAProxy back. <code>RENEWED_DOMAINS</code> is set by certbot.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># /etc/letsencrypt/renewal-hooks/deploy/haproxy.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">set</span> -e
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">HAPROXY_CERT_DIR</span><span class="o">=</span><span class="s2">&#34;/etc/haproxy/certs&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Process each renewed domain</span>
</span></span><span class="line"><span class="cl"><span class="k">for</span> domain in <span class="nv">$RENEWED_DOMAINS</span><span class="p">;</span> <span class="k">do</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># Find the certificate directory</span>
</span></span><span class="line"><span class="cl">    <span class="nv">CERT_DIR</span><span class="o">=</span><span class="s2">&#34;/etc/letsencrypt/live/</span><span class="nv">$domain</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="o">[</span> -d <span class="s2">&#34;</span><span class="nv">$CERT_DIR</span><span class="s2">&#34;</span> <span class="o">]</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">        <span class="c1"># Combine cert and key for HAProxy</span>
</span></span><span class="line"><span class="cl">        cat <span class="s2">&#34;</span><span class="nv">$CERT_DIR</span><span class="s2">/fullchain.pem&#34;</span> <span class="s2">&#34;</span><span class="nv">$CERT_DIR</span><span class="s2">/privkey.pem&#34;</span> &gt; <span class="s2">&#34;</span><span class="nv">$HAPROXY_CERT_DIR</span><span class="s2">/</span><span class="nv">$domain</span><span class="s2">.pem&#34;</span>
</span></span><span class="line"><span class="cl">        chmod <span class="m">600</span> <span class="s2">&#34;</span><span class="nv">$HAPROXY_CERT_DIR</span><span class="s2">/</span><span class="nv">$domain</span><span class="s2">.pem&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="nb">echo</span> <span class="s2">&#34;Updated certificate for </span><span class="nv">$domain</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="k">fi</span>
</span></span><span class="line"><span class="cl"><span class="k">done</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Reload HAProxy</span>
</span></span><span class="line"><span class="cl">systemctl reload haproxy <span class="o">||</span> systemctl start haproxy
</span></span></code></pre></div><p>Make it executable:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">chmod +x /etc/letsencrypt/renewal-hooks/deploy/haproxy.sh
</span></span></code></pre></div><h2 id="method-3-zero-downtime-renewal-recommended">Method 3: Zero-Downtime Renewal (Recommended) <a class="anchor" data-pagefind-ignore href="#method-3-zero-downtime-renewal-recommended" aria-label="Link to this section">#</a></h2>
<p>This approach uses HAProxy&rsquo;s runtime API to reload certificates without restart or reload. Existing connections are untouched.</p>
<h3 id="haproxy-configuration-1">HAProxy Configuration <a class="anchor" data-pagefind-ignore href="#haproxy-configuration-1" aria-label="Link to this section">#</a></h3>
<p>Changes from Method 1:</p>
<ul>
<li><code>expose-fd listeners</code> on the stats socket: allows seamless reloads for the fallback path.</li>
<li><code>strict-sni</code>: refuse TLS handshakes for names without a certificate instead of serving a wrong one.</li>
<li>The ACME backend moves to <code>127.0.0.1:8080</code>.</li>
</ul>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy"># /etc/haproxy/haproxy.cfg

global
    log /dev/log local0
    chroot /var/lib/haproxy
    stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners
    stats timeout 30s
    user haproxy
    group haproxy
    daemon
    
    # Enable runtime API for certificate management
    ssl-default-bind-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384
    ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
    ssl-default-bind-options ssl-min-ver TLSv1.2 no-tls-tickets

defaults
    log global
    mode http
    option httplog
    timeout connect 5s
    timeout client  50s
    timeout server  50s

# HTTP Frontend
frontend http_frontend
    bind *:80
    
    # ACME challenge path
    acl is_acme path_beg /.well-known/acme-challenge/
    use_backend acme_backend if is_acme
    
    # Redirect to HTTPS
    http-request redirect scheme https code 301 unless is_acme

# HTTPS Frontend
frontend https_frontend
    bind *:443 ssl crt /etc/haproxy/certs/ strict-sni alpn h2,http/1.1
    
    http-response set-header Strict-Transport-Security &#34;max-age=63072000&#34;
    
    default_backend web_servers

# ACME challenge backend
backend acme_backend
    server acme 127.0.0.1:8080

backend web_servers
    balance roundrobin
    option httpchk GET /health
    server web1 192.168.1.10:8080 check
    server web2 192.168.1.11:8080 check
</code></pre><h3 id="zero-downtime-certificate-update-script">Zero-Downtime Certificate Update Script <a class="anchor" data-pagefind-ignore href="#zero-downtime-certificate-update-script" aria-label="Link to this section">#</a></h3>
<p>For a certificate HAProxy already has loaded, the script swaps it in memory with <code>set ssl cert</code> and <code>commit ssl cert</code>. A new certificate is not known to the running process yet, so it falls back to a reload.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># /usr/local/bin/haproxy-cert-update.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">set</span> -e
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">HAPROXY_CERT_DIR</span><span class="o">=</span><span class="s2">&#34;/etc/haproxy/certs&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">HAPROXY_SOCKET</span><span class="o">=</span><span class="s2">&#34;/run/haproxy/admin.sock&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">update_certificate<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">    <span class="nb">local</span> <span class="nv">domain</span><span class="o">=</span><span class="nv">$1</span>
</span></span><span class="line"><span class="cl">    <span class="nb">local</span> <span class="nv">cert_dir</span><span class="o">=</span><span class="s2">&#34;/etc/letsencrypt/live/</span><span class="nv">$domain</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="nb">local</span> <span class="nv">combined_cert</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$HAPROXY_CERT_DIR</span><span class="s2">/</span><span class="nv">$domain</span><span class="s2">.pem&#34;</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># Combine certificates</span>
</span></span><span class="line"><span class="cl">    cat <span class="s2">&#34;</span><span class="nv">$cert_dir</span><span class="s2">/fullchain.pem&#34;</span> <span class="s2">&#34;</span><span class="nv">$cert_dir</span><span class="s2">/privkey.pem&#34;</span> &gt; <span class="s2">&#34;</span><span class="nv">$combined_cert</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    chmod <span class="m">600</span> <span class="s2">&#34;</span><span class="nv">$combined_cert</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># Check if HAProxy is running with this certificate</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="nb">echo</span> <span class="s2">&#34;show ssl cert&#34;</span> <span class="p">|</span> socat stdio <span class="s2">&#34;</span><span class="nv">$HAPROXY_SOCKET</span><span class="s2">&#34;</span> <span class="p">|</span> grep -q <span class="s2">&#34;</span><span class="nv">$combined_cert</span><span class="s2">&#34;</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">        <span class="c1"># Update certificate in running HAProxy: the payload must be sent in the</span>
</span></span><span class="line"><span class="cl">        <span class="c1"># same session as &#34;set ssl cert&#34;, the commit in a second session</span>
</span></span><span class="line"><span class="cl">        <span class="o">{</span> <span class="nb">echo</span> <span class="s2">&#34;set ssl cert </span><span class="nv">$combined_cert</span><span class="s2"> &lt;&lt;&#34;</span><span class="p">;</span> cat <span class="s2">&#34;</span><span class="nv">$combined_cert</span><span class="s2">&#34;</span><span class="p">;</span> <span class="nb">echo</span> <span class="s2">&#34;&#34;</span><span class="p">;</span> <span class="o">}</span> <span class="p">|</span> socat stdio <span class="s2">&#34;</span><span class="nv">$HAPROXY_SOCKET</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="nb">echo</span> <span class="s2">&#34;commit ssl cert </span><span class="nv">$combined_cert</span><span class="s2">&#34;</span> <span class="p">|</span> socat stdio <span class="s2">&#34;</span><span class="nv">$HAPROXY_SOCKET</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="nb">echo</span> <span class="s2">&#34;Certificate for </span><span class="nv">$domain</span><span class="s2"> updated in-place&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="k">else</span>
</span></span><span class="line"><span class="cl">        <span class="c1"># Certificate not yet loaded, reload HAProxy</span>
</span></span><span class="line"><span class="cl">        systemctl reload haproxy
</span></span><span class="line"><span class="cl">        <span class="nb">echo</span> <span class="s2">&#34;HAProxy reloaded for new certificate </span><span class="nv">$domain</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="k">fi</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Process the renewed certificate (certbot sets RENEWED_LINEAGE to its live directory)</span>
</span></span><span class="line"><span class="cl">update_certificate <span class="s2">&#34;</span><span class="k">$(</span>basename <span class="s2">&#34;</span><span class="nv">$RENEWED_LINEAGE</span><span class="s2">&#34;</span><span class="k">)</span><span class="s2">&#34;</span>
</span></span></code></pre></div><h3 id="haproxy-24-runtime-certificate-api">HAProxy 2.4+ Runtime Certificate API <a class="anchor" data-pagefind-ignore href="#haproxy-24-runtime-certificate-api" aria-label="Link to this section">#</a></h3>
<p>The same commands by hand, to inspect or update a certificate. The update only changes memory; the file on disk is what HAProxy loads at the next start.</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"># List certificates</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;show ssl cert&#34;</span> <span class="p">|</span> socat stdio /run/haproxy/admin.sock
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Show certificate details</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;show ssl cert /etc/haproxy/certs/example.com.pem&#34;</span> <span class="p">|</span> socat stdio /run/haproxy/admin.sock
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Update certificate in-place (HAProxy 2.4+): payload in the same session, then commit</span>
</span></span><span class="line"><span class="cl"><span class="o">{</span> <span class="nb">echo</span> <span class="s2">&#34;set ssl cert /etc/haproxy/certs/example.com.pem &lt;&lt;&#34;</span><span class="p">;</span> cat /etc/haproxy/certs/example.com.pem<span class="p">;</span> <span class="nb">echo</span> <span class="s2">&#34;&#34;</span><span class="p">;</span> <span class="o">}</span> <span class="p">|</span> socat stdio /run/haproxy/admin.sock
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;commit ssl cert /etc/haproxy/certs/example.com.pem&#34;</span> <span class="p">|</span> socat stdio /run/haproxy/admin.sock
</span></span></code></pre></div><h2 id="method-4-dns-01-challenge-wildcard-certificates">Method 4: DNS-01 Challenge (Wildcard Certificates) <a class="anchor" data-pagefind-ignore href="#method-4-dns-01-challenge-wildcard-certificates" aria-label="Link to this section">#</a></h2>
<p>For wildcard certificates or when HTTP challenges aren&rsquo;t possible. Certbot proves control by creating a TXT record through your DNS provider&rsquo;s API; port 80 is not involved.</p>
<h3 id="with-cloudflare-dns">With Cloudflare DNS <a class="anchor" data-pagefind-ignore href="#with-cloudflare-dns" aria-label="Link to this section">#</a></h3>
<p>Use an API token limited to editing DNS for the zone, not your global API key.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Install Cloudflare DNS plugin</span>
</span></span><span class="line"><span class="cl">apt install python3-certbot-dns-cloudflare
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Or, if certbot itself was installed with pip in /opt/certbot</span>
</span></span><span class="line"><span class="cl"><span class="c1"># (Ubuntu 24.04 and Debian 12 refuse a system-wide pip install)</span>
</span></span><span class="line"><span class="cl">/opt/certbot/bin/pip install certbot-dns-cloudflare
</span></span></code></pre></div><p>Create credentials file (readable by root only):</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/letsencrypt/cloudflare.ini</span>
</span></span><span class="line"><span class="cl"><span class="na">dns_cloudflare_api_token</span> <span class="o">=</span> <span class="s">your-api-token-here</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">chmod <span class="m">600</span> /etc/letsencrypt/cloudflare.ini
</span></span></code></pre></div><p>Request wildcard certificate:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">certbot certonly <span class="se">\
</span></span></span><span class="line"><span class="cl">  --dns-cloudflare <span class="se">\
</span></span></span><span class="line"><span class="cl">  --dns-cloudflare-credentials /etc/letsencrypt/cloudflare.ini <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d example.com <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d <span class="s1">&#39;*.example.com&#39;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  --email admin@example.com <span class="se">\
</span></span></span><span class="line"><span class="cl">  --agree-tos
</span></span></code></pre></div><h3 id="with-route53">With Route53 <a class="anchor" data-pagefind-ignore href="#with-route53" aria-label="Link to this section">#</a></h3>
<p>The plugin uses standard AWS credentials; an IAM role or <code>~/.aws/credentials</code> is better than exported keys.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">apt install python3-certbot-dns-route53
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Configure AWS credentials</span>
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_ACCESS_KEY_ID</span><span class="o">=</span>your-key
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_SECRET_ACCESS_KEY</span><span class="o">=</span>your-secret
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">certbot certonly <span class="se">\
</span></span></span><span class="line"><span class="cl">  --dns-route53 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d example.com <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d <span class="s1">&#39;*.example.com&#39;</span>
</span></span></code></pre></div><h2 id="automated-renewal-setup">Automated Renewal Setup <a class="anchor" data-pagefind-ignore href="#automated-renewal-setup" aria-label="Link to this section">#</a></h2>
<p>Certbot only renews certificates that are close to expiry, so running it twice a day is cheap. The <code>--deploy-hook</code> runs only when a certificate was actually renewed.</p>
<table>
	<thead>
			<tr>
					<th>Option</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Systemd timer</td>
					<td>Most systems; <code>Persistent=true</code> catches up on missed runs</td>
			</tr>
			<tr>
					<td>Cron</td>
					<td>Systems without systemd</td>
			</tr>
	</tbody>
</table>
<p>Packaged certbot often ships its own timer (<code>certbot.timer</code>) or cron entry. Use one scheduler, not both.</p>
<h3 id="systemd-timer">Systemd Timer <a class="anchor" data-pagefind-ignore href="#systemd-timer" aria-label="Link to this section">#</a></h3>
<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/certbot-renewal.service</span>
</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">Certbot Renewal</span>
</span></span><span class="line"><span class="cl"><span class="na">After</span><span class="o">=</span><span class="s">network-online.target</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">oneshot</span>
</span></span><span class="line"><span class="cl"><span class="na">ExecStart</span><span class="o">=</span><span class="s">/usr/bin/certbot renew --deploy-hook /etc/letsencrypt/renewal-hooks/deploy/haproxy.sh</span>
</span></span></code></pre></div><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/certbot-renewal.timer</span>
</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">Run certbot renewal twice daily</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">[Timer]</span>
</span></span><span class="line"><span class="cl"><span class="na">OnCalendar</span><span class="o">=</span><span class="s">*-*-* 00,12:00:00</span>
</span></span><span class="line"><span class="cl"><span class="na">RandomizedDelaySec</span><span class="o">=</span><span class="s">43200</span>
</span></span><span class="line"><span class="cl"><span class="na">Persistent</span><span class="o">=</span><span class="s">true</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">timers.target</span>
</span></span></code></pre></div><p>Enable the timer:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">systemctl daemon-reload
</span></span><span class="line"><span class="cl">systemctl <span class="nb">enable</span> certbot-renewal.timer
</span></span><span class="line"><span class="cl">systemctl start certbot-renewal.timer
</span></span></code></pre></div><h3 id="cron-job-alternative">Cron Job Alternative <a class="anchor" data-pagefind-ignore href="#cron-job-alternative" 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"># /etc/cron.d/certbot</span>
</span></span><span class="line"><span class="cl"><span class="m">0</span> 0,12 * * * root certbot renew --deploy-hook /etc/letsencrypt/renewal-hooks/deploy/haproxy.sh
</span></span></code></pre></div><h2 id="multi-domain-configuration">Multi-Domain Configuration <a class="anchor" data-pagefind-ignore href="#multi-domain-configuration" aria-label="Link to this section">#</a></h2>
<p>One HAProxy can serve many domains, each with its own certificate.</p>
<h3 id="separate-certificates-per-domain">Separate Certificates per Domain <a class="anchor" data-pagefind-ignore href="#separate-certificates-per-domain" aria-label="Link to this section">#</a></h3>
<p>List each PEM on the bind line and route on the SNI name.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend https_frontend
    bind *:443 ssl crt /etc/haproxy/certs/example.com.pem crt /etc/haproxy/certs/example.org.pem
    
    # Route based on SNI
    use_backend example_com_servers if { ssl_fc_sni example.com }
    use_backend example_org_servers if { ssl_fc_sni example.org }
</code></pre><h3 id="certificate-directory">Certificate Directory <a class="anchor" data-pagefind-ignore href="#certificate-directory" aria-label="Link to this section">#</a></h3>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend https_frontend
    # Load all .pem files from directory
    bind *:443 ssl crt /etc/haproxy/certs/
</code></pre><p>HAProxy automatically matches certificates based on SNI. New files are picked up at the next reload.</p>
<h3 id="request-multiple-certificates">Request Multiple Certificates <a class="anchor" data-pagefind-ignore href="#request-multiple-certificates" aria-label="Link to this section">#</a></h3>
<p>Each line in <code>DOMAINS</code> becomes one certificate; the first name is the certificate name and the file name in <code>/etc/letsencrypt/live/</code>.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># /usr/local/bin/request-certs.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">DOMAINS</span><span class="o">=(</span>
</span></span><span class="line"><span class="cl">    <span class="s2">&#34;example.com www.example.com&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="s2">&#34;api.example.com&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="s2">&#34;app.example.com&#34;</span>
</span></span><span class="line"><span class="cl"><span class="o">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">for</span> domain_set in <span class="s2">&#34;</span><span class="si">${</span><span class="nv">DOMAINS</span><span class="p">[@]</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">;</span> <span class="k">do</span>
</span></span><span class="line"><span class="cl">    <span class="nv">primary</span><span class="o">=</span><span class="k">$(</span><span class="nb">echo</span> <span class="nv">$domain_set</span> <span class="p">|</span> awk <span class="s1">&#39;{print $1}&#39;</span><span class="k">)</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    certbot certonly <span class="se">\
</span></span></span><span class="line"><span class="cl">        --webroot <span class="se">\
</span></span></span><span class="line"><span class="cl">        -w /var/www/letsencrypt <span class="se">\
</span></span></span><span class="line"><span class="cl">        <span class="k">$(for</span> d in <span class="nv">$domain_set</span><span class="p">;</span> <span class="k">do</span> <span class="nb">echo</span> <span class="s2">&#34;-d </span><span class="nv">$d</span><span class="s2">&#34;</span><span class="p">;</span> <span class="k">done)</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">        --cert-name <span class="nv">$primary</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">        --non-interactive
</span></span><span class="line"><span class="cl"><span class="k">done</span>
</span></span></code></pre></div><h2 id="complete-production-setup">Complete Production Setup <a class="anchor" data-pagefind-ignore href="#complete-production-setup" aria-label="Link to this section">#</a></h2>
<p>Method 3 with host routing and security headers.</p>
<h3 id="haproxy-configuration-2">HAProxy Configuration <a class="anchor" data-pagefind-ignore href="#haproxy-configuration-2" aria-label="Link to this section">#</a></h3>
<table>
	<thead>
			<tr>
					<th>Part</th>
					<th>What it does</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>global</code> ssl settings</td>
					<td>TLS 1.2 minimum, modern ciphers, for client (<code>bind</code>) and backend (<code>server</code>) sides</td>
			</tr>
			<tr>
					<td><code>listen stats</code></td>
					<td>Stats page and <code>/metrics</code> on 8404; change <code>admin:changeme</code></td>
			</tr>
			<tr>
					<td><code>http_frontend</code></td>
					<td>ACME challenges to <code>acme_backend</code>, everything else 301 to HTTPS</td>
			</tr>
			<tr>
					<td><code>https_frontend</code></td>
					<td>All certificates from <code>/etc/haproxy/certs/</code>, security headers, <code>X-Forwarded-Proto</code>, routing by Host</td>
			</tr>
			<tr>
					<td><code>app_servers</code></td>
					<td>Sticky sessions with the <code>SERVERID</code> cookie</td>
			</tr>
	</tbody>
</table>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy"># /etc/haproxy/haproxy.cfg

global
    log /dev/log local0
    log /dev/log local1 notice
    chroot /var/lib/haproxy
    stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners
    stats timeout 30s
    user haproxy
    group haproxy
    daemon
    
    maxconn 50000
    nbthread 4
    
    # Modern SSL settings
    ssl-default-bind-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305
    ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
    ssl-default-bind-options ssl-min-ver TLSv1.2 no-tls-tickets
    ssl-default-server-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384
    ssl-default-server-options ssl-min-ver TLSv1.2 no-tls-tickets
    tune.ssl.default-dh-param 2048

defaults
    log global
    mode http
    option httplog
    option dontlognull
    option forwardfor
    option http-server-close
    timeout connect 5s
    timeout client  50s
    timeout server  50s
    timeout http-request 10s
    timeout http-keep-alive 10s

# Stats
listen stats
    bind *:8404
    stats enable
    stats uri /stats
    stats refresh 10s
    stats auth admin:changeme
    http-request use-service prometheus-exporter if { path /metrics }

# HTTP Frontend
frontend http_frontend
    bind *:80
    
    # ACME challenges
    acl is_acme path_beg /.well-known/acme-challenge/
    use_backend acme_backend if is_acme
    
    # Redirect to HTTPS with 301
    http-request redirect scheme https code 301 unless is_acme

# HTTPS Frontend
frontend https_frontend
    bind *:443 ssl crt /etc/haproxy/certs/ strict-sni alpn h2,http/1.1
    
    # Security headers
    http-response set-header Strict-Transport-Security &#34;max-age=63072000; includeSubDomains; preload&#34;
    http-response set-header X-Content-Type-Options &#34;nosniff&#34;
    http-response set-header X-Frame-Options &#34;SAMEORIGIN&#34;
    http-response set-header X-XSS-Protection &#34;1; mode=block&#34;
    
    # Log SSL info
    http-request capture req.hdr(Host) len 50
    http-request set-header X-Forwarded-Proto https
    http-request set-header X-SSL-Client-Verify %[ssl_c_verify]
    http-request set-header X-SSL-Client-DN %{+Q}[ssl_c_s_dn]
    
    # Route based on host
    use_backend api_servers if { hdr(host) -i api.example.com }
    use_backend app_servers if { hdr(host) -i app.example.com }
    default_backend web_servers

# ACME challenge backend
backend acme_backend
    server acme 127.0.0.1:8080

# Web servers
backend web_servers
    balance roundrobin
    option httpchk GET /health
    http-check expect status 200
    server web1 192.168.1.10:8080 check inter 5s
    server web2 192.168.1.11:8080 check inter 5s

# API servers
backend api_servers
    balance leastconn
    option httpchk GET /api/health
    http-check expect status 200
    server api1 192.168.1.20:8080 check inter 5s
    server api2 192.168.1.21:8080 check inter 5s

# App servers
backend app_servers
    balance roundrobin
    option httpchk GET /health
    cookie SERVERID insert indirect nocache
    server app1 192.168.1.30:8080 check cookie app1
    server app2 192.168.1.31:8080 check cookie app2
</code></pre><h3 id="complete-deployment-script">Complete Deployment Script <a class="anchor" data-pagefind-ignore href="#complete-deployment-script" aria-label="Link to this section">#</a></h3>
<p>Sets up the challenge server as a systemd service on port 8080 and requests a certificate for each domain given as argument:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># /usr/local/bin/setup-haproxy-letsencrypt.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">set</span> -e
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Run this with HAProxy already up (it needs at least one certificate in</span>
</span></span><span class="line"><span class="cl"><span class="c1"># /etc/haproxy/certs, see the initial request above) and the deploy hook below in place.</span>
</span></span><span class="line"><span class="cl"><span class="nv">DOMAINS</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$@</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">EMAIL</span><span class="o">=</span><span class="s2">&#34;admin@example.com&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">HAPROXY_CERT_DIR</span><span class="o">=</span><span class="s2">&#34;/etc/haproxy/certs&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">WEBROOT</span><span class="o">=</span><span class="s2">&#34;/var/www/letsencrypt&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create directories</span>
</span></span><span class="line"><span class="cl">mkdir -p <span class="nv">$HAPROXY_CERT_DIR</span>
</span></span><span class="line"><span class="cl">mkdir -p <span class="nv">$WEBROOT</span>/.well-known/acme-challenge
</span></span><span class="line"><span class="cl">chown -R www-data:www-data <span class="nv">$WEBROOT</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create ACME challenge server</span>
</span></span><span class="line"><span class="cl">cat &gt; /etc/systemd/system/acme-challenge.service <span class="s">&lt;&lt; &#39;EOF&#39;
</span></span></span><span class="line"><span class="cl"><span class="s">[Unit]
</span></span></span><span class="line"><span class="cl"><span class="s">Description=ACME Challenge Server
</span></span></span><span class="line"><span class="cl"><span class="s">After=network.target
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[Service]
</span></span></span><span class="line"><span class="cl"><span class="s">Type=simple
</span></span></span><span class="line"><span class="cl"><span class="s">User=www-data
</span></span></span><span class="line"><span class="cl"><span class="s">WorkingDirectory=/var/www/letsencrypt
</span></span></span><span class="line"><span class="cl"><span class="s">ExecStart=/usr/bin/python3 -m http.server 8080
</span></span></span><span class="line"><span class="cl"><span class="s">Restart=always
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[Install]
</span></span></span><span class="line"><span class="cl"><span class="s">WantedBy=multi-user.target
</span></span></span><span class="line"><span class="cl"><span class="s">EOF</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">systemctl daemon-reload
</span></span><span class="line"><span class="cl">systemctl <span class="nb">enable</span> acme-challenge
</span></span><span class="line"><span class="cl">systemctl start acme-challenge
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Request certificates</span>
</span></span><span class="line"><span class="cl"><span class="k">for</span> domain in <span class="nv">$DOMAINS</span><span class="p">;</span> <span class="k">do</span>
</span></span><span class="line"><span class="cl">    <span class="nb">echo</span> <span class="s2">&#34;Requesting certificate for </span><span class="nv">$domain</span><span class="s2">...&#34;</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    certbot certonly <span class="se">\
</span></span></span><span class="line"><span class="cl">        --webroot <span class="se">\
</span></span></span><span class="line"><span class="cl">        -w <span class="nv">$WEBROOT</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">        -d <span class="nv">$domain</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">        --email <span class="nv">$EMAIL</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">        --agree-tos <span class="se">\
</span></span></span><span class="line"><span class="cl">        --non-interactive <span class="se">\
</span></span></span><span class="line"><span class="cl">        --deploy-hook /etc/letsencrypt/renewal-hooks/deploy/haproxy.sh
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># Create HAProxy certificate</span>
</span></span><span class="line"><span class="cl">    cat /etc/letsencrypt/live/<span class="nv">$domain</span>/fullchain.pem <span class="se">\
</span></span></span><span class="line"><span class="cl">        /etc/letsencrypt/live/<span class="nv">$domain</span>/privkey.pem <span class="se">\
</span></span></span><span class="line"><span class="cl">        &gt; <span class="nv">$HAPROXY_CERT_DIR</span>/<span class="nv">$domain</span>.pem
</span></span><span class="line"><span class="cl">    chmod <span class="m">600</span> <span class="nv">$HAPROXY_CERT_DIR</span>/<span class="nv">$domain</span>.pem
</span></span><span class="line"><span class="cl"><span class="k">done</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Reload HAProxy</span>
</span></span><span class="line"><span class="cl">systemctl reload haproxy
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;Setup complete!&#34;</span>
</span></span></code></pre></div><h3 id="deploy-hook-script">Deploy Hook Script <a class="anchor" data-pagefind-ignore href="#deploy-hook-script" aria-label="Link to this section">#</a></h3>
<p>The production version of the hook: runtime update first, reload as fallback, everything logged to <code>/var/log/certbot-haproxy.log</code>. It uses <code>RENEWED_LINEAGE</code>, the live directory of the renewed certificate.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># /etc/letsencrypt/renewal-hooks/deploy/haproxy.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">set</span> -e
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">HAPROXY_CERT_DIR</span><span class="o">=</span><span class="s2">&#34;/etc/haproxy/certs&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">HAPROXY_SOCKET</span><span class="o">=</span><span class="s2">&#34;/run/haproxy/admin.sock&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">LOG_FILE</span><span class="o">=</span><span class="s2">&#34;/var/log/certbot-haproxy.log&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">log<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">    <span class="nb">echo</span> <span class="s2">&#34;</span><span class="k">$(</span>date <span class="s1">&#39;+%Y-%m-%d %H:%M:%S&#39;</span><span class="k">)</span><span class="s2"> - </span><span class="nv">$1</span><span class="s2">&#34;</span> &gt;&gt; <span class="nv">$LOG_FILE</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">update_haproxy_cert<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">    <span class="nb">local</span> <span class="nv">domain</span><span class="o">=</span><span class="nv">$1</span>
</span></span><span class="line"><span class="cl">    <span class="nb">local</span> <span class="nv">cert_path</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$HAPROXY_CERT_DIR</span><span class="s2">/</span><span class="nv">$domain</span><span class="s2">.pem&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="nb">local</span> <span class="nv">le_cert</span><span class="o">=</span><span class="s2">&#34;/etc/letsencrypt/live/</span><span class="nv">$domain</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># Combine certificates</span>
</span></span><span class="line"><span class="cl">    cat <span class="s2">&#34;</span><span class="nv">$le_cert</span><span class="s2">/fullchain.pem&#34;</span> <span class="s2">&#34;</span><span class="nv">$le_cert</span><span class="s2">/privkey.pem&#34;</span> &gt; <span class="s2">&#34;</span><span class="nv">$cert_path</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    chmod <span class="m">600</span> <span class="s2">&#34;</span><span class="nv">$cert_path</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># Try runtime update first (HAProxy 2.4+)</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="o">[</span> -S <span class="s2">&#34;</span><span class="nv">$HAPROXY_SOCKET</span><span class="s2">&#34;</span> <span class="o">]</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">        <span class="k">if</span> <span class="nb">echo</span> <span class="s2">&#34;show ssl cert </span><span class="nv">$cert_path</span><span class="s2">&#34;</span> <span class="p">|</span> socat stdio <span class="s2">&#34;</span><span class="nv">$HAPROXY_SOCKET</span><span class="s2">&#34;</span> 2&gt;/dev/null <span class="p">|</span> grep -q <span class="s2">&#34;</span><span class="nv">$cert_path</span><span class="s2">&#34;</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">            <span class="c1"># Certificate exists, update in-place: payload first, commit in a</span>
</span></span><span class="line"><span class="cl">            <span class="c1"># separate session (HAProxy 3.2 and later ignore a commit sent after the payload)</span>
</span></span><span class="line"><span class="cl">            <span class="o">{</span>
</span></span><span class="line"><span class="cl">                <span class="nb">echo</span> <span class="s2">&#34;set ssl cert </span><span class="nv">$cert_path</span><span class="s2"> &lt;&lt;&#34;</span>
</span></span><span class="line"><span class="cl">                cat <span class="s2">&#34;</span><span class="nv">$cert_path</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">                <span class="nb">echo</span> <span class="s2">&#34;&#34;</span>
</span></span><span class="line"><span class="cl">            <span class="o">}</span> <span class="p">|</span> socat stdio <span class="s2">&#34;</span><span class="nv">$HAPROXY_SOCKET</span><span class="s2">&#34;</span> 2&gt;/dev/null
</span></span><span class="line"><span class="cl">            
</span></span><span class="line"><span class="cl">            <span class="k">if</span> <span class="nb">echo</span> <span class="s2">&#34;commit ssl cert </span><span class="nv">$cert_path</span><span class="s2">&#34;</span> <span class="p">|</span> socat stdio <span class="s2">&#34;</span><span class="nv">$HAPROXY_SOCKET</span><span class="s2">&#34;</span> 2&gt;/dev/null <span class="p">|</span> grep -q <span class="s2">&#34;Success&#34;</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">                log <span class="s2">&#34;Updated certificate for </span><span class="nv">$domain</span><span class="s2"> via runtime API&#34;</span>
</span></span><span class="line"><span class="cl">                <span class="k">return</span> <span class="m">0</span>
</span></span><span class="line"><span class="cl">            <span class="k">fi</span>
</span></span><span class="line"><span class="cl">        <span class="k">fi</span>
</span></span><span class="line"><span class="cl">    <span class="k">fi</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># Fallback to reload</span>
</span></span><span class="line"><span class="cl">    systemctl reload haproxy
</span></span><span class="line"><span class="cl">    log <span class="s2">&#34;Reloaded HAProxy for </span><span class="nv">$domain</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Process the renewed certificate (RENEWED_LINEAGE is /etc/letsencrypt/live/&lt;name&gt;;</span>
</span></span><span class="line"><span class="cl"><span class="c1"># RENEWED_DOMAINS lists every name on it, which may not have a live directory of its own)</span>
</span></span><span class="line"><span class="cl"><span class="nv">domain</span><span class="o">=</span><span class="k">$(</span>basename <span class="s2">&#34;</span><span class="nv">$RENEWED_LINEAGE</span><span class="s2">&#34;</span><span class="k">)</span>
</span></span><span class="line"><span class="cl">log <span class="s2">&#34;Processing renewal for </span><span class="nv">$domain</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">update_haproxy_cert <span class="s2">&#34;</span><span class="nv">$domain</span><span class="s2">&#34;</span>
</span></span></code></pre></div><h2 id="testing-and-verification">Testing and Verification <a class="anchor" data-pagefind-ignore href="#testing-and-verification" aria-label="Link to this section">#</a></h2>
<p>Check what clients actually get, then test the renewal path before it runs for real.</p>
<h3 id="test-certificate">Test Certificate <a class="anchor" data-pagefind-ignore href="#test-certificate" 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"># Check certificate</span>
</span></span><span class="line"><span class="cl">openssl s_client -connect example.com:443 -servername example.com &lt; /dev/null 2&gt;/dev/null <span class="p">|</span> openssl x509 -text -noout <span class="p">|</span> head -20
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Verify chain (s_client checks the served chain against the system trust store)</span>
</span></span><span class="line"><span class="cl">openssl s_client -connect example.com:443 -servername example.com -verify_return_error &lt; /dev/null 2&gt;<span class="p">&amp;</span><span class="m">1</span> <span class="p">|</span> grep <span class="s2">&#34;Verify return code&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check expiration</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="p">|</span> openssl s_client -connect example.com:443 -servername example.com 2&gt;/dev/null <span class="p">|</span> openssl x509 -noout -dates
</span></span></code></pre></div><h3 id="ssl-labs-test">SSL Labs Test <a class="anchor" data-pagefind-ignore href="#ssl-labs-test" aria-label="Link to this section">#</a></h3>
<p>A full external grade of your TLS configuration.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">curl -s <span class="s2">&#34;https://api.ssllabs.com/api/v3/analyze?host=example.com&amp;publish=off&amp;all=done&#34;</span>
</span></span></code></pre></div><h3 id="test-renewal">Test Renewal <a class="anchor" data-pagefind-ignore href="#test-renewal" aria-label="Link to this section">#</a></h3>
<p>Runs the whole renewal against the staging server without replacing certificates.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">certbot renew --dry-run
</span></span></code></pre></div><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<h3 id="common-issues">Common Issues <a class="anchor" data-pagefind-ignore href="#common-issues" aria-label="Link to this section">#</a></h3>
<ol>
<li><strong>Permission denied on socket</strong>:</li>
</ol>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">chmod <span class="m">660</span> /run/haproxy/admin.sock
</span></span><span class="line"><span class="cl">chown haproxy:haproxy /run/haproxy/admin.sock
</span></span></code></pre></div><ol start="2">
<li><strong>Certificate not found</strong>:</li>
</ol>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check certificate directory</span>
</span></span><span class="line"><span class="cl">ls -la /etc/haproxy/certs/
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Verify HAProxy can load them (it reads certificates as root before</span>
</span></span><span class="line"><span class="cl"><span class="c1"># dropping privileges, so root-only 600 files are fine)</span>
</span></span><span class="line"><span class="cl">haproxy -c -f /etc/haproxy/haproxy.cfg
</span></span></code></pre></div><ol start="3">
<li><strong>ACME challenge fails</strong>:</li>
</ol>
<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 challenge server is running</span>
</span></span><span class="line"><span class="cl">curl http://localhost:8080/.well-known/acme-challenge/test
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check HAProxy routing</span>
</span></span><span class="line"><span class="cl">curl -H <span class="s2">&#34;Host: example.com&#34;</span> http://localhost/.well-known/acme-challenge/test
</span></span></code></pre></div><ol start="4">
<li><strong>SNI not matching</strong>:</li>
</ol>
<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 specific SNI</span>
</span></span><span class="line"><span class="cl">curl -v --resolve example.com:443:127.0.0.1 https://example.com/
</span></span></code></pre></div><h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Private keys.</strong> The combined PEM files contain the key: keep them mode 600, as the scripts do.</li>
<li><strong>DNS API credentials.</strong> <code>cloudflare.ini</code> or AWS keys can change your DNS; restrict their scope and file permissions.</li>
<li><strong>Stats page.</strong> Change <code>stats auth admin:changeme</code> and firewall port 8404.</li>
<li><strong>HSTS preload.</strong> Once preloaded, browsers refuse HTTP for the domain and its subdomains for a long time; enable it deliberately.</li>
</ul>
<h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub:
<a href="https://github.com/pderuiter/blog-haproxy-letsencrypt" rel="noopener">pderuiter/blog-haproxy-letsencrypt</a>. It creates an HAProxy VM on Proxmox, requests the certificates with certbot over HTTP-01 and installs the complete production setup from this post, with the runtime API deploy hook and the renewal timer; point your domains at the VM, run <code>terraform apply</code>, then <code>ansible-playbook site.yml</code> (try it against the Let&rsquo;s Encrypt staging server first).</p>
<h2 id="next-steps">Next Steps <a class="anchor" data-pagefind-ignore href="#next-steps" aria-label="Link to this section">#</a></h2>
<p>Next in the series: debugging HTTP headers in HAProxy, for troubleshooting web application issues.</p>
<h2 id="summary">Summary <a class="anchor" data-pagefind-ignore href="#summary" aria-label="Link to this section">#</a></h2>
<p>Key takeaways for HAProxy with Let&rsquo;s Encrypt:</p>
<ul>
<li>Combine fullchain.pem and privkey.pem for HAProxy certificates</li>
<li>Use HTTP-01 challenges for standard domains, DNS-01 for wildcards</li>
<li>Implement zero-downtime certificate updates with HAProxy&rsquo;s runtime API</li>
<li>Set up automated renewal with systemd timers or cron</li>
<li>Use proper TLS settings for security (TLS 1.2+, strong ciphers)</li>
<li>Always enable HSTS for production sites</li>
</ul>
<p>With this setup, certificates renew and load themselves without manual work.</p>
]]></content:encoded></item><item><title>Implementing DNS over HTTPS (DoH) with BIND and nginx</title><link>https://blog.bsdserver.nl/implementing-dns-over-https-doh-with-bind-and-nginx/</link><guid isPermaLink="false">693b6f2679eb54000160a5b5</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:25:58 +0000</pubDate><description>First, a short side note. Personal viewpoint: I’m not a fan of DNS over HTTPS (DoH).</description><category>BIND</category><category>DNS</category><category>DNS over HTTPS</category><category>HTTPS</category><category>Security</category><category>nginx</category><category>Encryption</category><category>Homelab</category><category>Linux</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/dns-over-https-with-bind-and-nginx.png" medium="image"/><content:encoded><![CDATA[<p>First, a short side note.</p>
<p><strong>Personal viewpoint:</strong> I’m not a fan of DNS over HTTPS (DoH). The main reason is not encryption itself (encryption is a good thing) but <em>how</em> DoH is implemented and deployed.</p>
<p><strong>Facts:</strong></p>
<ul>
<li>DoH carries DNS inside regular HTTPS traffic (TCP/443), indistinguishable from normal web traffic. Firewall rules, DNS logging, traffic inspection and policy enforcement become much harder, or impossible without TLS interception.</li>
<li>DNS over TLS (DoT) uses a dedicated port (TCP/853). It is just as encrypted, but easy to identify, monitor, rate-limit or block at the network edge.</li>
<li>Major public DoH providers include Google, Cloudflare and others. Clients that use them outsource resolution to a third party, which then holds query timing, source IPs (or coarse location) and domain access patterns. That data is valuable for analytics and profiling, whatever the privacy promises.</li>
<li>DoH bypasses split-horizon DNS, ignores local policy tools (RPZ, DNS firewalling, internal blocklists) and complicates incident response, since DNS activity hides inside generic HTTPS flows.</li>
</ul>
<p><strong>Personal viewpoint (clearly marked):</strong> This centralisation is what I’m uncomfortable with. DoT still lets organisations run their <em>own</em> encrypted resolvers without losing visibility. I actively block DoH in my environments using Response Policy Zones (RPZ) in BIND, and support encrypted DNS via DoT where it makes sense.</p>
<p>In short: encryption is not the problem. <strong>Loss of control, visibility, and centralisation of data at a few hyperscalers is.</strong></p>
<h2 id="what-is-dns-over-https">What is DNS over HTTPS? <a class="anchor" data-pagefind-ignore href="#what-is-dns-over-https" aria-label="Link to this section">#</a></h2>
<p>DNS over HTTPS (DoH) encrypts DNS queries within regular HTTPS traffic, making them indistinguishable from normal web browsing. This provides privacy benefits but requires a different architectural approach than DoT.</p>
<p>If your clients are going to use DoH anyway, it is better that they use <em>your</em> resolver. This post puts a DoH front end on your BIND resolver, with nginx as a reverse proxy, so your own policies (RPZ, split horizon, logging) still apply.</p>
<h2 id="why-doh">Why DoH? <a class="anchor" data-pagefind-ignore href="#why-doh" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Advantages/Disadvantages</th>
					<th>Description</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Privacy</td>
					<td>ISPs cannot see DNS queries</td>
			</tr>
			<tr>
					<td>Censorship resistance</td>
					<td>Hard to block (uses port 443)</td>
			</tr>
			<tr>
					<td>Browser integration</td>
					<td>Native support in Firefox, Chrome</td>
			</tr>
			<tr>
					<td>Enterprise bypass</td>
					<td>Can bypass network DNS policies</td>
			</tr>
	</tbody>
</table>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> when browsers or apps on your network expect DoH, or for roaming clients that must reach your resolver over networks that only allow HTTPS.</li>
<li><strong>Skip it</strong> when you control the clients: DoT (or plain DNS on a trusted network) is simpler to operate and to monitor.</li>
</ul>
<h2 id="understanding-dns-over-https">Understanding DNS over HTTPS <a class="anchor" data-pagefind-ignore href="#understanding-dns-over-https" aria-label="Link to this section">#</a></h2>
<h3 id="how-doh-works">How DoH Works <a class="anchor" data-pagefind-ignore href="#how-doh-works" aria-label="Link to this section">#</a></h3>
<p>DoH encapsulates DNS queries in HTTP/2 requests over TLS:</p>
<ol>
<li>Client sends DNS query as HTTP POST or GET to <code>/dns-query</code></li>
<li>Query encoded as <code>application/dns-message</code> (RFC 8484)</li>
<li>Response returned as HTTP response body</li>
<li>All traffic flows over standard HTTPS (port 443)</li>
</ol>
<p>With GET, the query goes base64url-encoded in the <code>?dns=</code> parameter; with POST, it is the raw request body.</p>
<h3 id="wire-format-vs-json">Wire Format vs JSON <a class="anchor" data-pagefind-ignore href="#wire-format-vs-json" aria-label="Link to this section">#</a></h3>
<p>DoH supports two formats:</p>
<table>
	<thead>
			<tr>
					<th></th>
					<th>Wire format (RFC 8484)</th>
					<th>JSON (Google/Cloudflare JSON API, not part of RFC 8484)</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Content-Type</td>
					<td><code>application/dns-message</code></td>
					<td><code>application/dns-json</code></td>
			</tr>
			<tr>
					<td>Content</td>
					<td>Standard DNS binary format over HTTP</td>
					<td>Human-readable JSON</td>
			</tr>
			<tr>
					<td>Strengths</td>
					<td>More efficient, widely supported</td>
					<td>Easier to debug and inspect</td>
			</tr>
			<tr>
					<td>Used by</td>
					<td>Browsers and system resolvers</td>
					<td>Some API-based clients</td>
			</tr>
	</tbody>
</table>
<p>Serve wire format; JSON is optional (see <a href="#json-api-support">JSON API Support</a>).</p>
<h2 id="architecture-options">Architecture Options <a class="anchor" data-pagefind-ignore href="#architecture-options" aria-label="Link to this section">#</a></h2>
<p>BIND 9.18 and later can serve DoH natively with the <code>http</code> statement:</p>
<pre tabindex="0"><code>tls doh-cert {
    cert-file &#34;/etc/bind/tls/cert.pem&#34;;
    key-file &#34;/etc/bind/tls/key.pem&#34;;
};

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

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