<?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>Security | A DevOps Blog</title><link>https://blog.bsdserver.nl/tag/security/</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>Fri, 20 Nov 2026 01:22:00 +0100</lastBuildDate><atom:link href="https://blog.bsdserver.nl/tag/security/rss/" rel="self" type="application/rss+xml"/><ttl>60</ttl><item><title>A Default-Deny NAT Firewall on OpenBSD pf, Managed with Terraform</title><link>https://blog.bsdserver.nl/default-deny-nat-firewall-openbsd-pf-terraform/</link><guid isPermaLink="true">https://blog.bsdserver.nl/default-deny-nat-firewall-openbsd-pf-terraform/</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 20 Nov 2026 01:22:00 +0100</pubDate><description>Build a default-deny OpenBSD pf firewall with NAT, port forwarding, a blocklist and QoS, managed through pfapid and its Terraform provider.</description><category>OpenBSD</category><category>Security</category><category>Networking</category><category>Terraform</category><category>Automation</category><category>API</category><media:content url="https://blog.bsdserver.nl/content/images/2026/11/pf-terraform-nat-firewall.png" medium="image"/><content:encoded><![CDATA[<p>pf is the best firewall I have worked with: one readable file, atomic reloads, NAT and queueing in the same language as the filter rules. What it lacks is an API. Every tool that wants to change a pf firewall ends up templating <code>pf.conf</code>, copying it over SSH and hoping <code>pfctl -f</code> likes it.</p>
<p>I wrote <a href="https://github.com/pderuiter/pfapid" rel="noopener">pfapid</a> to fix that: a small REST API for pf that runs on the firewall itself, with a <a href="https://registry.terraform.io/providers/pderuiter/pf/latest" rel="noopener">Terraform provider</a> on top. This post builds a complete NAT firewall with it: a default-deny base, outbound NAT, a port forward to a DMZ web server, a blocklist and QoS on the uplink.</p>
<h2 id="what-pfapid-manages-and-what-it-doesnt">What pfapid manages, and what it doesn&rsquo;t <a class="anchor" data-pagefind-ignore href="#what-pfapid-manages-and-what-it-doesnt" aria-label="Link to this section">#</a></h2>
<p>pfapid splits the firewall into two owners:</p>
<table>
	<thead>
			<tr>
					<th>Part</th>
					<th>Owned by</th>
					<th>Lives in</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Defaults, <code>block all</code>, antispoof, management access</td>
					<td>You, by hand or config management</td>
					<td><code>/etc/pf.conf</code></td>
			</tr>
			<tr>
					<td>Filter and NAT rules, per unit of work</td>
					<td>Terraform via pfapid</td>
					<td>Anchors <code>api/&lt;name&gt;</code></td>
			</tr>
			<tr>
					<td>Contents of tables such as <code>&lt;blocklist&gt;</code></td>
					<td>Terraform via pfapid</td>
					<td>Tables declared in <code>pf.conf</code></td>
			</tr>
			<tr>
					<td>HFSC queues and the rules that classify into them</td>
					<td>Terraform via pfapid</td>
					<td>The <code>api-qos</code> anchor and a queue include</td>
			</tr>
	</tbody>
</table>
<p>The base ruleset is the part you can&rsquo;t afford to get wrong, so the API can&rsquo;t touch it. Whatever Terraform does, the <code>block</code> and management rules in <code>pf.conf</code> come first.</p>
<h3 id="why-not-just-template-pfconf">Why not just template pf.conf? <a class="anchor" data-pagefind-ignore href="#why-not-just-template-pfconf" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong><code>terraform plan</code> asks pf.</strong> The provider sends the rules to the firewall, where pfapid runs <code>pfctl -n</code> on them. A rule pf would refuse fails the plan, not the apply, and the plan shows the exact lines pf will load.</li>
<li><strong>Commit-confirm.</strong> Every change is loaded, then rolled back by the firewall itself unless the provider confirms it within <code>confirm_timeout</code>. If an apply cuts off the path between Terraform and the firewall, the change undoes itself.</li>
<li><strong>Drift detection.</strong> Someone runs <code>pfctl</code> by hand at 3 a.m.? The next plan warns, and the next apply puts the rules back.</li>
<li><strong>Small blast radius.</strong> pfapid runs privilege-separated: the HTTPS side runs as <code>_pfapid</code> under <code>pledge(&quot;stdio inet&quot;)</code>, and only a tiny root process runs <code>pfctl</code>. Clients authenticate with mTLS and are scoped to anchors and tables. There is no raw pf.conf passthrough: rules are typed objects, rendered and checked before pf sees them.</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> when firewall rules belong to the same change as the thing they protect: a new service, a Kubernetes cluster, a customer network. They get reviewed and planned together.</li>
<li><strong>Skip it</strong> for a firewall nobody changes, or one with a single admin who is happy with <code>vi /etc/pf.conf</code>. A text file with good comments is hard to beat.</li>
</ul>
<h2 id="the-network">The network <a class="anchor" data-pagefind-ignore href="#the-network" aria-label="Link to this section">#</a></h2>
<pre tabindex="0"><code>                 internet
                     |
               wan  vio0   203.0.113.2/24, 2001:db8:1::2/64   (egress)
          +----------------------+
 mgmt     |                      |  lan  vio1   10.0.10.1/24, 2001:db8:10::1/64
 vio3 ----+   OpenBSD + pfapid   +-------------  office clients, VoIP phones
 192.168. |                      |
 100.1/24 |                      |  dmz  vio2   10.0.20.1/24, 2001:db8:20::1/64
          +----------------------+-------------  web server 10.0.20.10, 2001:db8:20::10
</code></pre><p>The rules use <strong>interface groups</strong> (<code>wan</code>, <code>lan</code>, <code>dmz</code>, <code>mgmt</code>), never device names. When you replace a NIC or move a network to a VLAN, you add the new interface to the group and no rule changes:</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/hostname.vio0 and friends: one &#34;group&#34; line each</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s1">&#39;group wan&#39;</span> &gt;&gt; /etc/hostname.vio0
</span></span><span class="line"><span class="cl">ifconfig vio0 group wan
</span></span></code></pre></div><p>What we want:</p>
<table>
	<thead>
			<tr>
					<th>From</th>
					<th>To</th>
					<th>What</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>lan</td>
					<td>internet</td>
					<td>Everything, IPv4 behind NAT, IPv6 routed</td>
			</tr>
			<tr>
					<td>dmz</td>
					<td>internet</td>
					<td>DNS, NTP and HTTPS only (updates)</td>
			</tr>
			<tr>
					<td>internet, lan</td>
					<td>web server</td>
					<td>TCP 80 and 443; IPv4 through a port forward on the wan address</td>
			</tr>
			<tr>
					<td><code>&lt;blocklist&gt;</code></td>
					<td>anything</td>
					<td>Nothing</td>
			</tr>
			<tr>
					<td>mgmt network</td>
					<td>firewall</td>
					<td>SSH and the pfapid API</td>
			</tr>
			<tr>
					<td>Everything else</td>
					<td></td>
					<td>Dropped and logged</td>
			</tr>
	</tbody>
</table>
<h2 id="step-1-install-pfapid">Step 1: Install pfapid <a class="anchor" data-pagefind-ignore href="#step-1-install-pfapid" aria-label="Link to this section">#</a></h2>
<p>pfapid ships as signed release archives for OpenBSD amd64 and arm64. Check the signature before you install it:</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"># on a workstation with gpg</span>
</span></span><span class="line"><span class="cl"><span class="nv">v</span><span class="o">=</span><span class="k">$(</span>curl -s https://api.github.com/repos/pderuiter/pfapid/releases/latest <span class="p">|</span>
</span></span><span class="line"><span class="cl">	sed -n <span class="s1">&#39;s/.*&#34;tag_name&#34;: *&#34;v\([^&#34;]*\)&#34;.*/\1/p&#39;</span><span class="k">)</span>
</span></span><span class="line"><span class="cl"><span class="nv">base</span><span class="o">=</span>https://github.com/pderuiter/pfapid/releases/download/v<span class="nv">$v</span>
</span></span><span class="line"><span class="cl">curl -sSLO <span class="nv">$base</span>/pfapid_<span class="si">${</span><span class="nv">v</span><span class="si">}</span>_openbsd_amd64.tar.gz
</span></span><span class="line"><span class="cl">curl -sSLO <span class="nv">$base</span>/pfapid_<span class="si">${</span><span class="nv">v</span><span class="si">}</span>_SHA256SUMS -O <span class="nv">$base</span>/pfapid_<span class="si">${</span><span class="nv">v</span><span class="si">}</span>_SHA256SUMS.sig
</span></span><span class="line"><span class="cl">curl -sSL https://raw.githubusercontent.com/pderuiter/pfapid/main/scripts/release-signing-key.asc <span class="p">|</span> gpg --import
</span></span><span class="line"><span class="cl">gpg --verify pfapid_<span class="si">${</span><span class="nv">v</span><span class="si">}</span>_SHA256SUMS.sig pfapid_<span class="si">${</span><span class="nv">v</span><span class="si">}</span>_SHA256SUMS
</span></span><span class="line"><span class="cl">shasum -a <span class="m">256</span> --ignore-missing -c pfapid_<span class="si">${</span><span class="nv">v</span><span class="si">}</span>_SHA256SUMS
</span></span></code></pre></div><p><code>gpg</code> must report a good signature from key <code>10A2F1058821D55C61E45C7EE97C02FEE2F51B23</code>. Then on the firewall, as root:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">tar xzf pfapid_*_openbsd_amd64.tar.gz
</span></span><span class="line"><span class="cl">useradd -s /sbin/nologin -d /var/empty -L daemon -c <span class="s2">&#34;pfapid network process&#34;</span> _pfapid
</span></span><span class="line"><span class="cl">install -o root -g wheel -m <span class="m">0555</span> pfapid /usr/local/sbin/pfapid
</span></span><span class="line"><span class="cl">install -o root -g wheel -m <span class="m">0555</span> deploy/rc.d/pfapid /etc/rc.d/pfapid
</span></span><span class="line"><span class="cl">install -d -o root -g wheel -m <span class="m">0700</span> /etc/pfapid /var/db/pfapid
</span></span><span class="line"><span class="cl">install -d -o root -g wheel -m <span class="m">0755</span> /etc/pf.anchors/api
</span></span><span class="line"><span class="cl"><span class="k">for</span> f in api.conf api-queues.conf api-qos.conf<span class="p">;</span> <span class="k">do</span>
</span></span><span class="line"><span class="cl">	<span class="o">[</span> -f /etc/pf.anchors/<span class="nv">$f</span> <span class="o">]</span> <span class="o">||</span> install -o root -g wheel -m <span class="m">0600</span> /dev/null /etc/pf.anchors/<span class="nv">$f</span>
</span></span><span class="line"><span class="cl"><span class="k">done</span>
</span></span></code></pre></div><p>The three empty files must exist before <code>pf.conf</code> includes them; pfapid fills them later.</p>
<p>pfapid has a built-in CA, so you don&rsquo;t need a PKI to get started. Create the CA and the server certificate, then a client certificate for Terraform:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">pfapid pki init -dns fw.example.net -ip 192.168.100.1
</span></span><span class="line"><span class="cl">pfapid pki issue -name tf-firewall -out /root/tf-firewall   <span class="c1"># writes tf-firewall.crt and .key</span>
</span></span></code></pre></div><p>Copy <code>/root/tf-firewall.crt</code>, <code>/root/tf-firewall.key</code> and the CA certificate (<code>/etc/pfapid/pki/ca.crt</code>) to the machine that runs Terraform, and delete the key from the firewall. A company CA, Vault or SPIFFE IDs work too; see <a href="https://github.com/pderuiter/pfapid/blob/main/docs/CERTIFICATES.md" rel="noopener">CERTIFICATES.md</a>.</p>
<h2 id="step-2-the-default-deny-base-ruleset">Step 2: The default-deny base ruleset <a class="anchor" data-pagefind-ignore href="#step-2-the-default-deny-base-ruleset" aria-label="Link to this section">#</a></h2>
<p>This file is yours. It holds everything that must hold no matter what the API does:</p>
<pre tabindex="0"><code># /etc/pf.conf: default-deny base ruleset for a pfapid-managed NAT firewall.
#
#   wan   vio0 (egress)  203.0.113.2/24, 2001:db8:1::2/64
#   lan   vio1           10.0.10.1/24,   2001:db8:10::1/64
#   dmz   vio2           10.0.20.1/24,   2001:db8:20::1/64
#   mgmt  vio3           192.168.100.1/24
admin_nets = &#34;192.168.100.0/24&#34;

set skip on lo
set block-policy drop
set loginterface egress

# Tables whose contents pfapid manages: declared empty, with persist,
# so a reload of this file keeps what Terraform put in them.
table &lt;dmz_web&gt; persist
table &lt;blocklist&gt; persist

# Default deny: nothing passes, in or out, unless a rule says so.
block log all

# Packets on lan or dmz must come from that network.
antispoof quick for { lan dmz }

# Management first, and quick: nothing in the API anchors can take it away.
pass in quick on mgmt proto tcp from $admin_nets to (mgmt) port { 22 8443 }

# IPv6 breaks without these: neighbour discovery and path MTU discovery.
pass quick inet6 proto icmp6 icmp6-type { unreach toobig timex paramprob \
	routersol routeradv neighbrsol neighbradv }

# The firewall offers no services to the inside networks.
block in quick on { lan dmz } to self

# The firewall&#39;s own traffic (DNS, NTP, syspatch).
pass out quick on egress from (egress)

# pfapid: QoS classification, then the API anchors.
include &#34;/etc/pf.anchors/api-queues.conf&#34;
anchor &#34;api-qos&#34;
load anchor &#34;api-qos&#34; from &#34;/etc/pf.anchors/api-qos.conf&#34;
anchor &#34;api/*&#34;
include &#34;/etc/pf.anchors/api.conf&#34;
</code></pre><p>Block by block:</p>
<ul>
<li><strong><code>block log all</code></strong> is the default-deny. pf uses the <em>last</em> matching rule, so every <code>pass</code> further down (and in the anchors) can open a hole, but nothing is open by default. It applies in both directions, which matters for forwarded traffic later.</li>
<li><strong><code>antispoof</code></strong> drops packets on lan or dmz with a source address that doesn&rsquo;t belong there.</li>
<li><strong>Management</strong> comes before the anchors and is <code>quick</code>: pf stops evaluating on the first <code>quick</code> match, so no anchor can override it. pfapid also refuses the <code>mgmt</code> group in any API rule.</li>
<li><strong>ICMPv6</strong> for neighbour discovery and path MTU. Without it, IPv6 breaks in slow, confusing ways. pfapid won&rsquo;t let the API block these either.</li>
<li><strong><code>block in quick on { lan dmz } to self</code></strong> keeps the inside networks away from the firewall&rsquo;s own addresses, including the API. If the firewall runs DNS or DHCP for the LAN, add a <code>pass in quick</code> for exactly that above this line.</li>
<li><strong>The pfapid hooks</strong>: the queue include and the <code>api-qos</code> anchor come before <code>anchor &quot;api/*&quot;</code>, so traffic is classified before an API rule passes it. <code>api.conf</code> is generated by pfapid with one <code>load anchor</code> line per anchor, so the anchors survive a reboot.</li>
</ul>
<p>Check the file, then load it with a way back. I locked myself out of my lab firewall while writing this post: my workstation wasn&rsquo;t in <code>admin_nets</code>. A background job that restores the old file after 90 seconds unless I cancel it brought the firewall back on its own:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">pfctl -nf /etc/pf.conf.new            <span class="c1"># syntax check, loads nothing</span>
</span></span><span class="line"><span class="cl">cp -p /etc/pf.conf /etc/pf.conf.good
</span></span><span class="line"><span class="cl">install -m <span class="m">0600</span> /etc/pf.conf.new /etc/pf.conf
</span></span><span class="line"><span class="cl">rm -f /tmp/pf-keep
</span></span><span class="line"><span class="cl"><span class="o">(</span> sleep 90<span class="p">;</span> <span class="o">[</span> -f /tmp/pf-keep <span class="o">]</span> <span class="o">||</span> <span class="o">{</span> cp -p /etc/pf.conf.good /etc/pf.conf<span class="p">;</span> pfctl -f /etc/pf.conf<span class="p">;</span> <span class="o">}</span> <span class="o">)</span> <span class="p">&amp;</span>
</span></span><span class="line"><span class="cl">pfctl -f /etc/pf.conf
</span></span><span class="line"><span class="cl"><span class="c1"># from a NEW ssh session: it works, keep it</span>
</span></span><span class="line"><span class="cl">touch /tmp/pf-keep
</span></span></code></pre></div><p>The test has to be a <em>new</em> connection: existing SSH sessions keep their state and survive a rule change that would lock out the next login.</p>
<h2 id="step-3-tell-pfapid-what-it-may-touch">Step 3: Tell pfapid what it may touch <a class="anchor" data-pagefind-ignore href="#step-3-tell-pfapid-what-it-may-touch" aria-label="Link to this section">#</a></h2>
<p><code>/etc/pfapid.json</code> (mode 0600, root) lists the interface groups, tables and queue devices the API may use, and which client may do what:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json"><span class="line"><span class="cl"><span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;listen&#34;</span><span class="p">:</span> <span class="s2">&#34;192.168.100.1:8443&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;tls&#34;</span><span class="p">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="nt">&#34;cert&#34;</span><span class="p">:</span> <span class="s2">&#34;/etc/pfapid/pki/server.crt&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="nt">&#34;key&#34;</span><span class="p">:</span> <span class="s2">&#34;/etc/pfapid/pki/server.key&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="nt">&#34;client_cas&#34;</span><span class="p">:</span> <span class="p">{</span> <span class="nt">&#34;pfapid&#34;</span><span class="p">:</span> <span class="s2">&#34;/etc/pfapid/pki/ca.crt&#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="nt">&#34;confirm_timeout&#34;</span><span class="p">:</span> <span class="s2">&#34;60s&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;policy&#34;</span><span class="p">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="nt">&#34;interfaces&#34;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&#34;wan&#34;</span><span class="p">,</span> <span class="s2">&#34;lan&#34;</span><span class="p">,</span> <span class="s2">&#34;dmz&#34;</span><span class="p">],</span>
</span></span><span class="line"><span class="cl">    <span class="nt">&#34;tables&#34;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&#34;dmz_web&#34;</span><span class="p">,</span> <span class="s2">&#34;blocklist&#34;</span><span class="p">],</span>
</span></span><span class="line"><span class="cl">    <span class="nt">&#34;queue_interfaces&#34;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&#34;vio0&#34;</span><span class="p">],</span>
</span></span><span class="line"><span class="cl">    <span class="nt">&#34;internal_nets&#34;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&#34;10.0.0.0/8&#34;</span><span class="p">,</span> <span class="s2">&#34;172.16.0.0/12&#34;</span><span class="p">,</span> <span class="s2">&#34;192.168.0.0/16&#34;</span><span class="p">,</span> <span class="s2">&#34;fd00::/8&#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="nt">&#34;clients&#34;</span><span class="p">:</span> <span class="p">[</span>
</span></span><span class="line"><span class="cl">    <span class="p">{</span> <span class="nt">&#34;name&#34;</span><span class="p">:</span> <span class="s2">&#34;tf-firewall&#34;</span><span class="p">,</span> <span class="nt">&#34;ca&#34;</span><span class="p">:</span> <span class="s2">&#34;pfapid&#34;</span><span class="p">,</span> <span class="nt">&#34;anchors&#34;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&#34;*&#34;</span><span class="p">],</span> <span class="nt">&#34;tables&#34;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&#34;dmz_web&#34;</span><span class="p">,</span> <span class="s2">&#34;blocklist&#34;</span><span class="p">],</span> <span class="nt">&#34;qos&#34;</span><span class="p">:</span> <span class="kc">true</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><strong><code>interfaces</code></strong> are the groups rules may name. <code>mgmt</code> is refused here and in every rule.</li>
<li><strong><code>tables</code></strong> must also be declared in <code>pf.conf</code>, empty and with <code>persist</code>.</li>
<li><strong><code>queue_interfaces</code></strong> are physical devices: pf can&rsquo;t hang a queue on a group.</li>
<li><strong><code>internal_nets</code></strong>: pfapid refuses NAT <em>between</em> two of these networks, a common mistake that hides where traffic really comes from. NAT from the LAN to the internet is fine.</li>
<li><strong><code>clients</code></strong>: <code>tf-firewall</code> (the certificate&rsquo;s CN) may manage every anchor, these two tables and QoS. A team that only owns its own service would get <code>&quot;anchors&quot;: [&quot;webshop-*&quot;]</code> and nothing else.</li>
</ul>
<p>Start it:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">pfapid -f /etc/pfapid.json -n       <span class="c1"># checks the configuration and certificates</span>
</span></span><span class="line"><span class="cl">rcctl <span class="nb">enable</span> pfapid
</span></span><span class="line"><span class="cl">rcctl start pfapid
</span></span></code></pre></div><h2 id="step-4-the-terraform-provider">Step 4: The Terraform provider <a class="anchor" data-pagefind-ignore href="#step-4-the-terraform-provider" aria-label="Link to this section">#</a></h2>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-hcl" data-lang="hcl"><span class="line"><span class="cl"><span class="k">terraform</span> {
</span></span><span class="line"><span class="cl">  <span class="k">required_providers</span> {
</span></span><span class="line"><span class="cl"><span class="n">    pf</span> <span class="o">=</span> {
</span></span><span class="line"><span class="cl"><span class="n">      source</span>  <span class="o">=</span> <span class="s2">&#34;pderuiter/pf&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      version</span> <span class="o">=</span> <span class="s2">&#34;~&gt; 0.1&#34;</span>
</span></span><span class="line"><span class="cl">    }
</span></span><span class="line"><span class="cl">  }
</span></span><span class="line"><span class="cl">}<span class="c1">
</span></span></span><span class="line"><span class="cl"><span class="c1">
</span></span></span><span class="line"><span class="cl"><span class="c1"># Endpoint and certificates come from the environment:
</span></span></span><span class="line"><span class="cl"><span class="c1">#   PFAPID_ENDPOINT, PFAPID_CA_CERT, PFAPID_CLIENT_CERT, PFAPID_CLIENT_KEY
</span></span></span><span class="line"><span class="cl"><span class="k">provider</span> <span class="s2">&#34;pf&#34;</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"><span class="nb">export</span> <span class="nv">PFAPID_ENDPOINT</span><span class="o">=</span>https://192.168.100.1:8443
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">PFAPID_CA_CERT</span><span class="o">=</span><span class="nv">$HOME</span>/.pfapid/ca.crt
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">PFAPID_CLIENT_CERT</span><span class="o">=</span><span class="nv">$HOME</span>/.pfapid/tf-firewall.crt
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">PFAPID_CLIENT_KEY</span><span class="o">=</span><span class="nv">$HOME</span>/.pfapid/tf-firewall.key
</span></span><span class="line"><span class="cl">terraform init
</span></span></code></pre></div><p>The provider is signed with the same key as the pfapid releases; <code>terraform init</code> checks that for you.</p>
<h2 id="step-5-tables">Step 5: Tables <a class="anchor" data-pagefind-ignore href="#step-5-tables" aria-label="Link to this section">#</a></h2>
<p>Tables are lists of addresses that rules refer to as <code>&lt;name&gt;</code>. Changing a table never reloads a rule, so it&rsquo;s the cheap way to add a web server or block a network. A table can hold IPv4 and IPv6 entries side by side:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-hcl" data-lang="hcl"><span class="line"><span class="cl"><span class="c1"># The web servers in the DMZ. pf rules reference &lt;dmz_web&gt;; changing the
</span></span></span><span class="line"><span class="cl"><span class="c1"># entries never reloads a rule.
</span></span></span><span class="line"><span class="cl"><span class="k">resource</span> <span class="s2">&#34;pf_table&#34; &#34;dmz_web&#34;</span> {
</span></span><span class="line"><span class="cl"><span class="n">  name</span>    <span class="o">=</span> <span class="s2">&#34;dmz_web&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">  entries</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&#34;10.0.20.10/32&#34;, &#34;2001:db8:20::10/128&#34;</span><span class="p">]</span>
</span></span><span class="line"><span class="cl">}<span class="c1">
</span></span></span><span class="line"><span class="cl"><span class="c1">
</span></span></span><span class="line"><span class="cl"><span class="c1"># Sources we never want to hear from.
</span></span></span><span class="line"><span class="cl"><span class="k">resource</span> <span class="s2">&#34;pf_table&#34; &#34;blocklist&#34;</span> {
</span></span><span class="line"><span class="cl"><span class="n">  name</span>    <span class="o">=</span> <span class="s2">&#34;blocklist&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">  entries</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&#34;198.51.100.0/24&#34;, &#34;2001:db8:bad::/48&#34;</span><span class="p">]</span>
</span></span><span class="line"><span class="cl">}
</span></span></code></pre></div><h2 id="step-6-filtering-and-outbound-nat">Step 6: Filtering and outbound NAT <a class="anchor" data-pagefind-ignore href="#step-6-filtering-and-outbound-nat" aria-label="Link to this section">#</a></h2>
<p>Each <code>pf_anchor</code> is one anchor, <code>api/&lt;name&gt;</code>, and its <code>rules</code> are loaded as a whole: pf is order-sensitive, so a ruleset is one atomic unit, never rule by rule. Split anchors along ownership: whoever owns the DMZ web server owns <code>dmz-web</code>.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-hcl" data-lang="hcl"><span class="line"><span class="cl"><span class="c1"># Anchor api/egress: the inside networks out to the internet.
</span></span></span><span class="line"><span class="cl"><span class="k">locals</span> {
</span></span><span class="line"><span class="cl"><span class="n">  lan4</span> <span class="o">=</span> <span class="s2">&#34;10.0.10.0/24&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">  lan6</span> <span class="o">=</span> <span class="s2">&#34;2001:db8:10::/64&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">  dmz4</span> <span class="o">=</span> <span class="s2">&#34;10.0.20.0/24&#34;</span>
</span></span><span class="line"><span class="cl">}
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">resource</span> <span class="s2">&#34;pf_anchor&#34; &#34;egress&#34;</span> {
</span></span><span class="line"><span class="cl"><span class="n">  name</span> <span class="o">=</span> <span class="s2">&#34;egress&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">  rules</span> <span class="o">=</span> <span class="p">[</span><span class="c1">
</span></span></span><span class="line"><span class="cl"><span class="c1">    # LAN clients may start anything; the out rule below decides where.
</span></span></span><span class="line"><span class="cl">    {
</span></span><span class="line"><span class="cl"><span class="n">      action</span>    <span class="o">=</span> <span class="s2">&#34;pass&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      direction</span> <span class="o">=</span> <span class="s2">&#34;in&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      interface</span> <span class="o">=</span> <span class="s2">&#34;lan&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      family</span>    <span class="o">=</span> <span class="s2">&#34;inet&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      from</span>      <span class="o">=</span><span class="n"> { prefixes</span> <span class="o">=</span> <span class="p">[</span><span class="k">local</span><span class="p">.</span><span class="k">lan4</span><span class="p">]</span> }
</span></span><span class="line"><span class="cl"><span class="n">      label</span>     <span class="o">=</span> <span class="s2">&#34;lan-in&#34;</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="n">      action</span>    <span class="o">=</span> <span class="s2">&#34;pass&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      direction</span> <span class="o">=</span> <span class="s2">&#34;in&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      interface</span> <span class="o">=</span> <span class="s2">&#34;lan&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      family</span>    <span class="o">=</span> <span class="s2">&#34;inet6&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      from</span>      <span class="o">=</span><span class="n"> { prefixes</span> <span class="o">=</span> <span class="p">[</span><span class="k">local</span><span class="p">.</span><span class="k">lan6</span><span class="p">]</span> }
</span></span><span class="line"><span class="cl"><span class="n">      label</span>     <span class="o">=</span> <span class="s2">&#34;lan-in&#34;</span>
</span></span><span class="line"><span class="cl">    }<span class="p">,</span><span class="c1">
</span></span></span><span class="line"><span class="cl"><span class="c1">    # DMZ servers only get DNS, NTP and HTTPS (updates) out.
</span></span></span><span class="line"><span class="cl">    {
</span></span><span class="line"><span class="cl"><span class="n">      action</span>    <span class="o">=</span> <span class="s2">&#34;pass&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      direction</span> <span class="o">=</span> <span class="s2">&#34;in&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      interface</span> <span class="o">=</span> <span class="s2">&#34;dmz&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      family</span>    <span class="o">=</span> <span class="s2">&#34;inet&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      protocol</span>  <span class="o">=</span> <span class="s2">&#34;udp&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      from</span>      <span class="o">=</span><span class="n"> { prefixes</span> <span class="o">=</span> <span class="p">[</span><span class="k">local</span><span class="p">.</span><span class="k">dmz4</span><span class="p">]</span> }
</span></span><span class="line"><span class="cl"><span class="n">      to</span>        <span class="o">=</span><span class="n"> { ports</span> <span class="o">=</span><span class="n"> [{ from</span> <span class="o">=</span><span class="n"> 53 }, { from</span> <span class="o">=</span> <span class="m">123</span> }<span class="p">]</span> }
</span></span><span class="line"><span class="cl"><span class="n">      label</span>     <span class="o">=</span> <span class="s2">&#34;dmz-out&#34;</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="n">      action</span>    <span class="o">=</span> <span class="s2">&#34;pass&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      direction</span> <span class="o">=</span> <span class="s2">&#34;in&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      interface</span> <span class="o">=</span> <span class="s2">&#34;dmz&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      family</span>    <span class="o">=</span> <span class="s2">&#34;inet&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      protocol</span>  <span class="o">=</span> <span class="s2">&#34;tcp&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      from</span>      <span class="o">=</span><span class="n"> { prefixes</span> <span class="o">=</span> <span class="p">[</span><span class="k">local</span><span class="p">.</span><span class="k">dmz4</span><span class="p">]</span> }
</span></span><span class="line"><span class="cl"><span class="n">      to</span>        <span class="o">=</span><span class="n"> { ports</span> <span class="o">=</span><span class="n"> [{ from</span> <span class="o">=</span> <span class="m">443</span> }<span class="p">]</span> }
</span></span><span class="line"><span class="cl"><span class="n">      label</span>     <span class="o">=</span> <span class="s2">&#34;dmz-out&#34;</span>
</span></span><span class="line"><span class="cl">    }<span class="p">,</span><span class="c1">
</span></span></span><span class="line"><span class="cl"><span class="c1">    # Out to the internet: IPv4 is translated to the wan address...
</span></span></span><span class="line"><span class="cl">    {
</span></span><span class="line"><span class="cl"><span class="n">      action</span>    <span class="o">=</span> <span class="s2">&#34;pass&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      direction</span> <span class="o">=</span> <span class="s2">&#34;out&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      interface</span> <span class="o">=</span> <span class="s2">&#34;wan&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      family</span>    <span class="o">=</span> <span class="s2">&#34;inet&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      from</span>      <span class="o">=</span><span class="n"> { prefixes</span> <span class="o">=</span> <span class="p">[</span><span class="k">local</span><span class="p">.</span><span class="k">lan4</span><span class="p">,</span> <span class="k">local</span><span class="p">.</span><span class="k">dmz4</span><span class="p">]</span> }
</span></span><span class="line"><span class="cl"><span class="n">      nat</span>       <span class="o">=</span><span class="n"> { kind</span> <span class="o">=</span><span class="n"> &#34;nat-to&#34;, interface</span> <span class="o">=</span> <span class="s2">&#34;wan&#34;</span> }
</span></span><span class="line"><span class="cl"><span class="n">      label</span>     <span class="o">=</span> <span class="s2">&#34;nat-out&#34;</span>
</span></span><span class="line"><span class="cl">    }<span class="p">,</span><span class="c1">
</span></span></span><span class="line"><span class="cl"><span class="c1">    # ...IPv6 is routed as is.
</span></span></span><span class="line"><span class="cl">    {
</span></span><span class="line"><span class="cl"><span class="n">      action</span>    <span class="o">=</span> <span class="s2">&#34;pass&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      direction</span> <span class="o">=</span> <span class="s2">&#34;out&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      interface</span> <span class="o">=</span> <span class="s2">&#34;wan&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      family</span>    <span class="o">=</span> <span class="s2">&#34;inet6&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      from</span>      <span class="o">=</span><span class="n"> { prefixes</span> <span class="o">=</span> <span class="p">[</span><span class="k">local</span><span class="p">.</span><span class="k">lan6</span><span class="p">]</span> }
</span></span><span class="line"><span class="cl"><span class="n">      label</span>     <span class="o">=</span> <span class="s2">&#34;v6-out&#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></code></pre></div><p>Things worth knowing:</p>
<ul>
<li><strong>Every rule names one family.</strong> pfapid refuses a rule that mixes IPv4 and IPv6: <code>pfctl</code> would silently turn it into two rules, and what&rsquo;s loaded would no longer match what you wrote. Tables are the way to cover both.</li>
<li><strong>Forwarded traffic is filtered twice.</strong> A packet from the LAN to the internet goes <em>in</em> on lan and <em>out</em> on wan, and with <code>block all</code> both directions need a <code>pass</code>. The <code>lan-in</code> rule allows everything in, but the out rules decide where it can go: only out on wan. A LAN client trying to reach the DMZ gets in on lan and is then dropped going out on dmz, unless a rule there allows it (the next anchor does, for the web ports).</li>
<li><strong>NAT sits on the out rule.</strong> <code>nat = { kind = &quot;nat-to&quot;, interface = &quot;wan&quot; }</code> renders as <code>nat-to (wan:0)</code>: the first address of wan, re-read when it changes, so this works with DHCP on the uplink too.</li>
<li><strong>IPv6 isn&rsquo;t translated.</strong> The LAN has a routed prefix, so the IPv6 rule just passes it.</li>
</ul>
<h2 id="step-7-port-forwarding-to-the-dmz">Step 7: Port forwarding to the DMZ <a class="anchor" data-pagefind-ignore href="#step-7-port-forwarding-to-the-dmz" aria-label="Link to this section">#</a></h2>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-hcl" data-lang="hcl"><span class="line"><span class="cl"><span class="c1"># Anchor api/dmz-web: publish the web server.
</span></span></span><span class="line"><span class="cl"><span class="k">locals</span> {
</span></span><span class="line"><span class="cl"><span class="n">  web_ports</span> <span class="o">=</span><span class="n"> [{ from</span> <span class="o">=</span><span class="n"> 80 }, { from</span> <span class="o">=</span> <span class="m">443</span> }<span class="p">]</span>
</span></span><span class="line"><span class="cl">}
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">resource</span> <span class="s2">&#34;pf_anchor&#34; &#34;dmz_web&#34;</span> {
</span></span><span class="line"><span class="cl"><span class="n">  name</span> <span class="o">=</span> <span class="s2">&#34;dmz-web&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">  rules</span> <span class="o">=</span> <span class="p">[</span><span class="c1">
</span></span></span><span class="line"><span class="cl"><span class="c1">    # IPv4: redirect the wan address to the server (port forward).
</span></span></span><span class="line"><span class="cl">    {
</span></span><span class="line"><span class="cl"><span class="n">      action</span>    <span class="o">=</span> <span class="s2">&#34;pass&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      direction</span> <span class="o">=</span> <span class="s2">&#34;in&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      interface</span> <span class="o">=</span> <span class="s2">&#34;wan&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      family</span>    <span class="o">=</span> <span class="s2">&#34;inet&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      protocol</span>  <span class="o">=</span> <span class="s2">&#34;tcp&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      to</span>        <span class="o">=</span><span class="n"> { interface</span> <span class="o">=</span><span class="n"> &#34;wan&#34;, ports</span> <span class="o">=</span> <span class="k">local</span><span class="p">.</span><span class="k">web_ports</span> }
</span></span><span class="line"><span class="cl"><span class="n">      nat</span>       <span class="o">=</span><span class="n"> { kind</span> <span class="o">=</span><span class="n"> &#34;rdr-to&#34;, address</span> <span class="o">=</span> <span class="s2">&#34;10.0.20.10/32&#34;</span> }
</span></span><span class="line"><span class="cl"><span class="n">      label</span>     <span class="o">=</span> <span class="s2">&#34;web-rdr&#34;</span>
</span></span><span class="line"><span class="cl">    }<span class="p">,</span><span class="c1">
</span></span></span><span class="line"><span class="cl"><span class="c1">    # IPv6: the server has a public address, so just let it through.
</span></span></span><span class="line"><span class="cl">    {
</span></span><span class="line"><span class="cl"><span class="n">      action</span>    <span class="o">=</span> <span class="s2">&#34;pass&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      direction</span> <span class="o">=</span> <span class="s2">&#34;in&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      interface</span> <span class="o">=</span> <span class="s2">&#34;wan&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      family</span>    <span class="o">=</span> <span class="s2">&#34;inet6&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      protocol</span>  <span class="o">=</span> <span class="s2">&#34;tcp&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      to</span>        <span class="o">=</span><span class="n"> { table</span> <span class="o">=</span><span class="n"> pf_table.dmz_web.name, ports</span> <span class="o">=</span> <span class="k">local</span><span class="p">.</span><span class="k">web_ports</span> }
</span></span><span class="line"><span class="cl"><span class="n">      label</span>     <span class="o">=</span> <span class="s2">&#34;web-in&#34;</span>
</span></span><span class="line"><span class="cl">    }<span class="p">,</span><span class="c1">
</span></span></span><span class="line"><span class="cl"><span class="c1">    # Forwarded traffic is filtered twice: in on wan (or lan), and out on
</span></span></span><span class="line"><span class="cl"><span class="c1">    # dmz. Without these the redirect above goes nowhere.
</span></span></span><span class="line"><span class="cl">    {
</span></span><span class="line"><span class="cl"><span class="n">      action</span>    <span class="o">=</span> <span class="s2">&#34;pass&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      direction</span> <span class="o">=</span> <span class="s2">&#34;out&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      interface</span> <span class="o">=</span> <span class="s2">&#34;dmz&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      family</span>    <span class="o">=</span> <span class="s2">&#34;inet&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      protocol</span>  <span class="o">=</span> <span class="s2">&#34;tcp&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      to</span>        <span class="o">=</span><span class="n"> { table</span> <span class="o">=</span><span class="n"> pf_table.dmz_web.name, ports</span> <span class="o">=</span> <span class="k">local</span><span class="p">.</span><span class="k">web_ports</span> }
</span></span><span class="line"><span class="cl"><span class="n">      label</span>     <span class="o">=</span> <span class="s2">&#34;web-out&#34;</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="n">      action</span>    <span class="o">=</span> <span class="s2">&#34;pass&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      direction</span> <span class="o">=</span> <span class="s2">&#34;out&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      interface</span> <span class="o">=</span> <span class="s2">&#34;dmz&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      family</span>    <span class="o">=</span> <span class="s2">&#34;inet6&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      protocol</span>  <span class="o">=</span> <span class="s2">&#34;tcp&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      to</span>        <span class="o">=</span><span class="n"> { table</span> <span class="o">=</span><span class="n"> pf_table.dmz_web.name, ports</span> <span class="o">=</span> <span class="k">local</span><span class="p">.</span><span class="k">web_ports</span> }
</span></span><span class="line"><span class="cl"><span class="n">      label</span>     <span class="o">=</span> <span class="s2">&#34;web-out&#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></code></pre></div><p>The <code>rdr-to</code> rule changes the destination of connections to the wan address on port 80 or 443 to <code>10.0.20.10</code>. The same <code>pass</code> rule creates the state, so there is no separate redirect-then-filter step to keep in sync. The redirected packet then leaves on dmz, and the <code>web-out</code> rules let it through: forget those and the port forward silently goes nowhere. Those same rules let LAN clients reach the web server directly.</p>
<p>For IPv6 the server has its own address, so there is nothing to translate: pass it in on wan and out on dmz.</p>
<h2 id="step-8-the-blocklist">Step 8: The blocklist <a class="anchor" data-pagefind-ignore href="#step-8-the-blocklist" aria-label="Link to this section">#</a></h2>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-hcl" data-lang="hcl"><span class="line"><span class="cl"><span class="c1"># Anchor api/blocklist. A quick block ends evaluation, so these win over
</span></span></span><span class="line"><span class="cl"><span class="c1"># any pass rule in another anchor.
</span></span></span><span class="line"><span class="cl"><span class="k">resource</span> <span class="s2">&#34;pf_anchor&#34; &#34;blocklist&#34;</span> {
</span></span><span class="line"><span class="cl"><span class="n">  name</span> <span class="o">=</span> <span class="s2">&#34;blocklist&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">  rules</span> <span class="o">=</span> <span class="p">[</span>
</span></span><span class="line"><span class="cl">    <span class="k">for</span> <span class="k">family</span> <span class="k">in</span> <span class="p">[</span><span class="s2">&#34;inet&#34;, &#34;inet6&#34;</span><span class="p">]</span> <span class="err">:</span> {
</span></span><span class="line"><span class="cl"><span class="n">      action</span>    <span class="o">=</span> <span class="s2">&#34;block&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      direction</span> <span class="o">=</span> <span class="s2">&#34;in&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      quick</span>     <span class="o">=</span> <span class="kt">true</span>
</span></span><span class="line"><span class="cl"><span class="n">      log</span>       <span class="o">=</span> <span class="kt">true</span>
</span></span><span class="line"><span class="cl"><span class="n">      interface</span> <span class="o">=</span> <span class="s2">&#34;wan&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      family</span>    <span class="o">=</span> <span class="k">family</span>
</span></span><span class="line"><span class="cl"><span class="n">      from</span>      <span class="o">=</span><span class="n"> { table</span> <span class="o">=</span> <span class="k">pf_table</span><span class="p">.</span><span class="k">blocklist</span><span class="p">.</span><span class="k">name</span> }
</span></span><span class="line"><span class="cl"><span class="n">      label</span>     <span class="o">=</span> <span class="s2">&#34;blocklist&#34;</span>
</span></span><span class="line"><span class="cl">    }
</span></span><span class="line"><span class="cl">  <span class="p">]</span>
</span></span><span class="line"><span class="cl">}
</span></span></code></pre></div><p><code>quick</code> ends evaluation on a match, so these blocks win over every pass rule in every anchor, whatever order pf evaluates the anchors in. <code>log</code> sends the dropped packets to <code>pflog0</code>.</p>
<p>Feed the table from wherever your threat data lives: a variable, a file, or a data source. Updating it is a table replace on the firewall, not a ruleset reload.</p>
<h2 id="step-9-qos-on-the-uplink">Step 9: QoS on the uplink <a class="anchor" data-pagefind-ignore href="#step-9-qos-on-the-uplink" aria-label="Link to this section">#</a></h2>
<p>An upload that fills the uplink makes everything else on the line feel slow: VoIP breaks up, SSH lags, and downloads crawl because their ACKs queue behind the upload. HFSC queues fix that by sharing the uplink by rule:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-hcl" data-lang="hcl"><span class="line"><span class="cl"><span class="c1"># QoS for a 100 Mbit/s uplink. Queues hang off a physical device (not a
</span></span></span><span class="line"><span class="cl"><span class="c1"># group), so the root names the device behind wan.
</span></span></span><span class="line"><span class="cl"><span class="k">variable</span> <span class="s2">&#34;uplink&#34;</span> {
</span></span><span class="line"><span class="cl"><span class="n">  type</span>    <span class="o">=</span> <span class="k">string</span>
</span></span><span class="line"><span class="cl"><span class="n">  default</span> <span class="o">=</span> <span class="s2">&#34;vio0&#34;</span>
</span></span><span class="line"><span class="cl">}
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">resource</span> <span class="s2">&#34;pf_qos&#34; &#34;uplink&#34;</span> {
</span></span><span class="line"><span class="cl"><span class="n">  queues</span> <span class="o">=</span> <span class="p">[</span>
</span></span><span class="line"><span class="cl"><span class="n">    { name</span> <span class="o">=</span><span class="n"> &#34;uplink&#34;, interface</span> <span class="o">=</span><span class="n"> var.uplink, bandwidth</span> <span class="o">=</span><span class="n"> &#34;100M&#34;, max</span> <span class="o">=</span> <span class="s2">&#34;100M&#34;</span> }<span class="p">,</span>
</span></span><span class="line"><span class="cl"><span class="n">    { name</span> <span class="o">=</span><span class="n"> &#34;std&#34;, parent</span> <span class="o">=</span><span class="n"> &#34;uplink&#34;, bandwidth</span> <span class="o">=</span><span class="n"> &#34;60M&#34;, default</span> <span class="o">=</span><span class="n"> true, flows</span> <span class="o">=</span> <span class="m">1024</span> }<span class="p">,</span>
</span></span><span class="line"><span class="cl"><span class="n">    { name</span> <span class="o">=</span><span class="n"> &#34;voip&#34;, parent</span> <span class="o">=</span><span class="n"> &#34;uplink&#34;, bandwidth</span> <span class="o">=</span><span class="n"> &#34;10M&#34;, min</span> <span class="o">=</span> <span class="s2">&#34;10M&#34;</span> }<span class="p">,</span>
</span></span><span class="line"><span class="cl"><span class="n">    { name</span> <span class="o">=</span><span class="n"> &#34;interactive&#34;, parent</span> <span class="o">=</span><span class="n"> &#34;uplink&#34;, bandwidth</span> <span class="o">=</span><span class="n"> &#34;10M&#34;, min</span> <span class="o">=</span> <span class="s2">&#34;5M&#34;</span> }<span class="p">,</span>
</span></span><span class="line"><span class="cl"><span class="n">    { name</span> <span class="o">=</span><span class="n"> &#34;bulk&#34;, parent</span> <span class="o">=</span><span class="n"> &#34;uplink&#34;, bandwidth</span> <span class="o">=</span><span class="n"> &#34;20M&#34;, max</span> <span class="o">=</span> <span class="s2">&#34;40M&#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="n">  rules</span> <span class="o">=</span> <span class="p">[</span><span class="c1">
</span></span></span><span class="line"><span class="cl"><span class="c1">    # Classify where the state is created: in on lan or dmz. pf queues the
</span></span></span><span class="line"><span class="cl"><span class="c1">    # packets of that connection when they leave wan. Match rules run in
</span></span></span><span class="line"><span class="cl"><span class="c1">    # order and the last one that matches decides, so general rules first.
</span></span></span><span class="line"><span class="cl"><span class="c1">    #
</span></span></span><span class="line"><span class="cl"><span class="c1">    # All TCP from the LAN: data in std, bare ACKs in interactive. A full
</span></span></span><span class="line"><span class="cl"><span class="c1">    # uplink then can&#39;t hold back the ACKs that keep downloads going.
</span></span></span><span class="line"><span class="cl">    {
</span></span><span class="line"><span class="cl"><span class="n">      direction</span> <span class="o">=</span> <span class="s2">&#34;in&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      interface</span> <span class="o">=</span> <span class="s2">&#34;lan&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      family</span>    <span class="o">=</span> <span class="s2">&#34;inet&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      protocol</span>  <span class="o">=</span> <span class="s2">&#34;tcp&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      queue</span>     <span class="o">=</span><span class="n"> { name</span> <span class="o">=</span><span class="n"> &#34;std&#34;, priority</span> <span class="o">=</span> <span class="s2">&#34;interactive&#34;</span> }
</span></span><span class="line"><span class="cl"><span class="n">      label</span>     <span class="o">=</span> <span class="s2">&#34;qos-acks&#34;</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="n">      direction</span> <span class="o">=</span> <span class="s2">&#34;in&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      interface</span> <span class="o">=</span> <span class="s2">&#34;lan&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      family</span>    <span class="o">=</span> <span class="s2">&#34;inet&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      protocol</span>  <span class="o">=</span> <span class="s2">&#34;tcp&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      to</span>        <span class="o">=</span><span class="n"> { ports</span> <span class="o">=</span><span class="n"> [{ from</span> <span class="o">=</span> <span class="m">22</span> }<span class="p">]</span> }
</span></span><span class="line"><span class="cl"><span class="n">      queue</span>     <span class="o">=</span><span class="n"> { name</span> <span class="o">=</span> <span class="s2">&#34;interactive&#34;</span> }
</span></span><span class="line"><span class="cl"><span class="n">      label</span>     <span class="o">=</span> <span class="s2">&#34;qos-ssh&#34;</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="n">      direction</span> <span class="o">=</span> <span class="s2">&#34;in&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      interface</span> <span class="o">=</span> <span class="s2">&#34;lan&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      family</span>    <span class="o">=</span> <span class="s2">&#34;inet&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      protocol</span>  <span class="o">=</span> <span class="s2">&#34;udp&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      to</span>        <span class="o">=</span><span class="n"> { ports</span> <span class="o">=</span><span class="n"> [{ from</span> <span class="o">=</span><span class="n"> 5060, to</span> <span class="o">=</span><span class="n"> 5061 }, { from</span> <span class="o">=</span><span class="n"> 10000, to</span> <span class="o">=</span> <span class="m">20000</span> }<span class="p">]</span> }
</span></span><span class="line"><span class="cl"><span class="n">      queue</span>     <span class="o">=</span><span class="n"> { name</span> <span class="o">=</span> <span class="s2">&#34;voip&#34;</span> }
</span></span><span class="line"><span class="cl"><span class="n">      prio</span>      <span class="o">=</span><span class="n"> { normal</span> <span class="o">=</span> <span class="m">6</span> }
</span></span><span class="line"><span class="cl"><span class="n">      label</span>     <span class="o">=</span> <span class="s2">&#34;qos-voip&#34;</span>
</span></span><span class="line"><span class="cl">    }<span class="p">,</span><span class="c1">
</span></span></span><span class="line"><span class="cl"><span class="c1">    # Offsite backups from the DMZ: capped, and last in line.
</span></span></span><span class="line"><span class="cl">    {
</span></span><span class="line"><span class="cl"><span class="n">      direction</span> <span class="o">=</span> <span class="s2">&#34;in&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      interface</span> <span class="o">=</span> <span class="s2">&#34;dmz&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      family</span>    <span class="o">=</span> <span class="s2">&#34;inet&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      protocol</span>  <span class="o">=</span> <span class="s2">&#34;tcp&#34;</span>
</span></span><span class="line"><span class="cl"><span class="n">      to</span>        <span class="o">=</span><span class="n"> { ports</span> <span class="o">=</span><span class="n"> [{ from</span> <span class="o">=</span> <span class="m">873</span> }<span class="p">]</span> }
</span></span><span class="line"><span class="cl"><span class="n">      queue</span>     <span class="o">=</span><span class="n"> { name</span> <span class="o">=</span> <span class="s2">&#34;bulk&#34;</span> }
</span></span><span class="line"><span class="cl"><span class="n">      prio</span>      <span class="o">=</span><span class="n"> { normal</span> <span class="o">=</span> <span class="m">1</span> }
</span></span><span class="line"><span class="cl"><span class="n">      label</span>     <span class="o">=</span> <span class="s2">&#34;qos-backup&#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></code></pre></div><p>How it fits together:</p>
<ul>
<li><strong>Queues shape what <em>leaves</em> an interface.</strong> These queues sit on the wan device, so they shape uploads. To shape downloads, put a second tree on the LAN device.</li>
<li><strong>The parent caps the total</strong> at 100M with <code>max</code>; set it slightly below your real upload speed so the queue builds here, where pf controls it, not in the modem. Children share it by <code>bandwidth</code>, <code>min</code> is a guarantee, <code>max</code> a hard cap. pfapid refuses children that add up to more than their parent; <code>pfctl</code> would accept that.</li>
<li><strong><code>std</code> is the default</strong> and an FQ-CoDel queue (<code>flows = 1024</code>): it keeps one heavy flow from adding latency to all the others.</li>
<li><strong>Classify where the connection starts.</strong> The rules match <code>in on lan</code> (or dmz); pf stores the queue in the connection&rsquo;s state and uses it when its packets leave wan. Keep that habit: a <code>match out on wan</code> rule never sees the replies to connections opened from the internet, such as the web server&rsquo;s responses.</li>
<li><strong>Two queues in one rule</strong>: <code>queue = { name = &quot;std&quot;, priority = &quot;interactive&quot; }</code> puts data in <code>std</code> and bare TCP ACKs in <code>interactive</code>. That one line is what keeps downloads fast during a big upload.</li>
<li><strong><code>prio</code></strong> is pf&rsquo;s simple 0–7 priority on interfaces without HFSC queues, such as lan here: VoIP towards the phones goes first too.</li>
<li><strong>QoS rules can only classify.</strong> They&rsquo;re <code>match</code> rules with no <code>pass</code>, <code>block</code> or NAT, so QoS can never change what the firewall lets through. That&rsquo;s also why it&rsquo;s a separate permission (<code>&quot;qos&quot;: true</code>).</li>
</ul>
<h2 id="step-10-plan-and-apply">Step 10: Plan and apply <a class="anchor" data-pagefind-ignore href="#step-10-plan-and-apply" aria-label="Link to this section">#</a></h2>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">terraform plan
</span></span></code></pre></div><p>Each anchor&rsquo;s plan includes <code>pf_rules</code>: the rules exactly as pf will load them, as <code>pfctl -nv</code> on the firewall printed them. This is what the plan showed in my lab (the QoS root was on <code>vio1</code> there):</p>
<pre tabindex="0"><code>pf_anchor.dmz_web:
  &#34;pass in on wan inet proto tcp from any to (wan) port = 80 flags S/SA label \&#34;web-rdr\&#34; rdr-to 10.0.20.10&#34;,
  &#34;pass in on wan inet proto tcp from any to (wan) port = 443 flags S/SA label \&#34;web-rdr\&#34; rdr-to 10.0.20.10&#34;,
  &#34;pass in on wan inet6 proto tcp from any to &lt;dmz_web&gt; port = 80 flags S/SA label \&#34;web-in\&#34;&#34;,
  ...
pf_anchor.egress:
  &#34;pass out on wan inet from 10.0.10.0/24 to any flags S/SA label \&#34;nat-out\&#34; nat-to (wan:0) round-robin&#34;,
  &#34;pass out on wan inet from 10.0.20.0/24 to any flags S/SA label \&#34;nat-out\&#34; nat-to (wan:0) round-robin&#34;,
  ...
pf_qos.uplink:
  &#34;queue uplink on vio1 bandwidth 100M, max 100M&#34;,
  &#34;queue std parent uplink flows 1024 bandwidth 60M default&#34;,
  ...
  &#34;match in on lan inet proto tcp all set (queue(std, interactive)) label \&#34;qos-acks\&#34;&#34;,
</code></pre><p>Lists become one line per port and per prefix, and pf adds its defaults (<code>flags S/SA</code>, <code>round-robin</code>). You see that before anything changes, not after.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">terraform apply
</span></span></code></pre></div><pre tabindex="0"><code>pf_table.dmz_web: Creation complete after 0s [id=dmz_web]
pf_table.blocklist: Creation complete after 0s [id=blocklist]
pf_anchor.egress: Creation complete after 0s [id=egress]
pf_qos.uplink: Creation complete after 0s [id=qos]
pf_anchor.dmz_web: Creation complete after 0s [id=dmz-web]
pf_anchor.blocklist: Creation complete after 0s [id=blocklist]

Apply complete! Resources: 6 added, 0 changed, 0 destroyed.
</code></pre><p>Each change was loaded, confirmed by the provider over the same connection, and only then written to pfapid&rsquo;s state. A second <code>terraform plan</code> reports no changes.</p>
<h2 id="step-11-check-it-on-the-firewall">Step 11: Check it on the firewall <a class="anchor" data-pagefind-ignore href="#step-11-check-it-on-the-firewall" aria-label="Link to this section">#</a></h2>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">pfctl -sA                    <span class="c1"># anchors: api, api/blocklist, api/dmz-web, api/egress, api-qos</span>
</span></span><span class="line"><span class="cl">pfctl -a api/egress -vsr     <span class="c1"># an anchor&#39;s rules, with counters</span>
</span></span><span class="line"><span class="cl">pfctl -t blocklist -T show   <span class="c1"># table contents</span>
</span></span><span class="line"><span class="cl">pfctl -vsq                   <span class="c1"># queues, with packets and drops</span>
</span></span><span class="line"><span class="cl">tcpdump -n -e -ttt -i pflog0 <span class="c1"># what the default-deny and the blocklist drop, live</span>
</span></span></code></pre></div><h2 id="the-guardrails-in-action">The guardrails in action <a class="anchor" data-pagefind-ignore href="#the-guardrails-in-action" aria-label="Link to this section">#</a></h2>
<p><strong>Drift.</strong> I flushed an anchor by hand with <code>pfctl -a api/dmz-web -F rules</code>. The next plan:</p>
<pre tabindex="0"><code>Warning: pf anchor api/dmz-web differs from its committed rules

The rules loaded in pf were changed outside pfapid. The next apply loads the
configured rules again.
Expected:
  pass in on wan inet proto tcp from any to (wan) port = 80 flags S/SA label &#34;web-rdr&#34; rdr-to 10.0.20.10
  ...
Plan: 0 to add, 1 to change, 0 to destroy.
</code></pre><p><code>terraform apply</code> loaded the rules again.</p>
<p><strong>The management interface.</strong> A rule that opens RDP on <code>mgmt</code> fails at plan time:</p>
<pre tabindex="0"><code>Error: Rules rejected by the firewall

pfapid: 400 invalid: rule 0: invalid: interface &#34;mgmt&#34; is not allowed
</code></pre><p><strong>A rule pf won&rsquo;t take.</strong> pfapid runs <code>pfctl -n</code> during the plan, so a rule pf would refuse fails <code>terraform plan</code>, with pf&rsquo;s own error message, before anything is loaded.</p>
<h2 id="limits-worth-knowing">Limits worth knowing <a class="anchor" data-pagefind-ignore href="#limits-worth-knowing" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>One firewall, one provider block.</strong> For an HA pair, configure two providers (with <code>alias</code>) and apply the same modules to both; pfsync keeps the states in sync, not the rules.</li>
<li><strong><code>self</code> is expanded when <code>pf.conf</code> loads.</strong> If the firewall&rsquo;s addresses change, reload the base ruleset.</li>
<li><strong>No hairpin NAT.</strong> LAN clients reach the web server on its DMZ address, not on the public one. Use split DNS.</li>
<li><strong>Queues are bit rates, not percentages</strong>: pf doesn&rsquo;t support percentages in HFSC yet.</li>
</ul>
<p>Everything in this post was planned and applied with provider v0.1.0 and pfapid v0.1.2 on an OpenBSD 7.9 lab VM, and the pf output shown is what pf loaded there. The code, the design notes and the pf behaviour pfapid relies on are on GitHub: <a href="https://github.com/pderuiter/pfapid" rel="noopener">pfapid</a> and <a href="https://github.com/pderuiter/terraform-provider-pf" rel="noopener">terraform-provider-pf</a>. Issues and pull requests are welcome.</p>
]]></content:encoded></item><item><title>HAProxy mTLS: Securing API Access with Mutual TLS Authentication</title><link>https://blog.bsdserver.nl/haproxy-mtls-securing-api-access-with-mutual-tls-authentication/</link><guid isPermaLink="false">693b755d79eb54000160a60f</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:52:29 +0000</pubDate><description>Mutual TLS (mTLS) provides strong authentication by requiring both client and server to present certificates.</description><category>HAProxy</category><category>mTLS</category><category>Security</category><category>TLS</category><category>Certificates</category><category>API</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/haproxy-mtls.png" medium="image"/><content:encoded><![CDATA[<p>Mutual TLS (mTLS) provides strong authentication by requiring both client and server to present certificates. API keys and passwords can leak and be replayed; a client certificate proves identity during the TLS handshake, before any request reaches your application.</p>
<p>This guide builds a small internal CA, configures HAProxy to require client certificates, passes the certificate identity to the backends, authorizes by CN, OU or fingerprint, and revokes certificates with a CRL.</p>
<h2 id="what-is-mtls">What is mTLS? <a class="anchor" data-pagefind-ignore href="#what-is-mtls" aria-label="Link to this section">#</a></h2>
<p>In standard TLS, only the server presents a certificate. With mTLS:</p>
<ol>
<li>Server presents its certificate to the client</li>
<li>Client verifies the server certificate</li>
<li>Client presents its certificate to the server</li>
<li>Server verifies the client certificate</li>
</ol>
<p>Both parties are authenticated. HAProxy does the client check, so the backends do not need any TLS code.</p>
<h2 id="why-mtls">Why mTLS? <a class="anchor" data-pagefind-ignore href="#why-mtls" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Service-to-service communication</strong>: Microservices authenticating each other</li>
<li><strong>API security</strong>: Authenticating API clients without passwords</li>
<li><strong>Zero-trust networks</strong>: Verifying identity at every connection</li>
<li><strong>IoT devices</strong>: Authenticating embedded devices</li>
<li><strong>B2B integrations</strong>: Partner API access with certificate-based auth</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 machine clients you control or issue certificates to: services, devices, partners.</li>
<li><strong>Skip it</strong> for public websites and end users in browsers. Installing certificates on user devices is painful; use OAuth or sessions instead.</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>Internal CA</td>
					<td>A locked-down host (here: the HAProxy host)</td>
					<td>Signs server and client certificates, publishes the CRL.</td>
			</tr>
			<tr>
					<td>HAProxy</td>
					<td>Load balancer</td>
					<td>Terminates TLS, checks the client certificate against the CA and CRL, applies ACLs, adds identity headers.</td>
			</tr>
			<tr>
					<td>Backends</td>
					<td>App servers</td>
					<td>Receive plain HTTP plus <code>X-Client-*</code> headers.</td>
			</tr>
			<tr>
					<td>Clients</td>
					<td>Services, devices, partners</td>
					<td>Present a certificate signed by the CA.</td>
			</tr>
	</tbody>
</table>
<p>The flow: client connects with its certificate → HAProxy verifies it against <code>ca-file</code> and <code>crl-file</code> → ACLs on CN/OU allow or deny → request goes to a backend with the client identity in headers.</p>
<h2 id="certificate-infrastructure-setup">Certificate Infrastructure Setup <a class="anchor" data-pagefind-ignore href="#certificate-infrastructure-setup" aria-label="Link to this section">#</a></h2>
<h3 id="create-a-certificate-authority-ca">Create a Certificate Authority (CA) <a class="anchor" data-pagefind-ignore href="#create-a-certificate-authority-ca" aria-label="Link to this section">#</a></h3>
<p>Your own CA decides who is a valid client: HAProxy trusts every certificate it signs. Use a private CA, never a public one, or anyone with a public certificate gets in.</p>
<p>What the <code>openssl.cnf</code> sections do:</p>
<table>
	<thead>
			<tr>
					<th>Section</th>
					<th>Use</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>CA_default</code></td>
					<td>Paths, 365-day default validity, 30-day CRL validity. <code>copy_extensions = copy</code> keeps the SAN from the CSR.</td>
			</tr>
			<tr>
					<td><code>policy_strict</code></td>
					<td>Only <code>commonName</code> is required in requests.</td>
			</tr>
			<tr>
					<td><code>v3_ca</code></td>
					<td>Extensions for the CA certificate itself.</td>
			</tr>
			<tr>
					<td><code>usr_cert</code></td>
					<td>Client certificates: <code>extendedKeyUsage = clientAuth</code>.</td>
			</tr>
			<tr>
					<td><code>server_cert</code></td>
					<td>Server certificates: <code>extendedKeyUsage = serverAuth</code>.</td>
			</tr>
	</tbody>
</table>
<p>The CA key is encrypted with a passphrase (<code>-aes256</code>) and the CA certificate is valid for 10 years.</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 CA directory structure</span>
</span></span><span class="line"><span class="cl">mkdir -p /etc/haproxy/ca/<span class="o">{</span>certs,crl,newcerts,private,csr<span class="o">}</span>
</span></span><span class="line"><span class="cl">chmod <span class="m">700</span> /etc/haproxy/ca/private
</span></span><span class="line"><span class="cl">touch /etc/haproxy/ca/index.txt
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="m">1000</span> &gt; /etc/haproxy/ca/serial
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create CA configuration</span>
</span></span><span class="line"><span class="cl">cat &gt; /etc/haproxy/ca/openssl.cnf <span class="s">&lt;&lt; &#39;EOF&#39;
</span></span></span><span class="line"><span class="cl"><span class="s">[ca]
</span></span></span><span class="line"><span class="cl"><span class="s">default_ca = CA_default
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[CA_default]
</span></span></span><span class="line"><span class="cl"><span class="s">dir               = /etc/haproxy/ca
</span></span></span><span class="line"><span class="cl"><span class="s">certs             = $dir/certs
</span></span></span><span class="line"><span class="cl"><span class="s">crl_dir           = $dir/crl
</span></span></span><span class="line"><span class="cl"><span class="s">new_certs_dir     = $dir/newcerts
</span></span></span><span class="line"><span class="cl"><span class="s">database          = $dir/index.txt
</span></span></span><span class="line"><span class="cl"><span class="s">serial            = $dir/serial
</span></span></span><span class="line"><span class="cl"><span class="s">private_key       = $dir/private/ca.key
</span></span></span><span class="line"><span class="cl"><span class="s">certificate       = $dir/certs/ca.crt
</span></span></span><span class="line"><span class="cl"><span class="s">default_md        = sha256
</span></span></span><span class="line"><span class="cl"><span class="s">default_days      = 365
</span></span></span><span class="line"><span class="cl"><span class="s">default_crl_days  = 30
</span></span></span><span class="line"><span class="cl"><span class="s">copy_extensions   = copy
</span></span></span><span class="line"><span class="cl"><span class="s">preserve          = no
</span></span></span><span class="line"><span class="cl"><span class="s">policy            = policy_strict
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[policy_strict]
</span></span></span><span class="line"><span class="cl"><span class="s">countryName             = optional
</span></span></span><span class="line"><span class="cl"><span class="s">stateOrProvinceName     = optional
</span></span></span><span class="line"><span class="cl"><span class="s">localityName            = optional
</span></span></span><span class="line"><span class="cl"><span class="s">organizationName        = optional
</span></span></span><span class="line"><span class="cl"><span class="s">organizationalUnitName  = optional
</span></span></span><span class="line"><span class="cl"><span class="s">commonName              = supplied
</span></span></span><span class="line"><span class="cl"><span class="s">emailAddress            = optional
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[req]
</span></span></span><span class="line"><span class="cl"><span class="s">default_bits        = 4096
</span></span></span><span class="line"><span class="cl"><span class="s">distinguished_name  = req_distinguished_name
</span></span></span><span class="line"><span class="cl"><span class="s">string_mask         = utf8only
</span></span></span><span class="line"><span class="cl"><span class="s">default_md          = sha256
</span></span></span><span class="line"><span class="cl"><span class="s">x509_extensions     = v3_ca
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[req_distinguished_name]
</span></span></span><span class="line"><span class="cl"><span class="s">countryName                     = Country Name (2 letter code)
</span></span></span><span class="line"><span class="cl"><span class="s">stateOrProvinceName             = State or Province Name
</span></span></span><span class="line"><span class="cl"><span class="s">localityName                    = Locality Name
</span></span></span><span class="line"><span class="cl"><span class="s">organizationName                = Organization Name
</span></span></span><span class="line"><span class="cl"><span class="s">organizationalUnitName          = Organizational Unit Name
</span></span></span><span class="line"><span class="cl"><span class="s">commonName                      = Common Name
</span></span></span><span class="line"><span class="cl"><span class="s">emailAddress                    = Email Address
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[v3_ca]
</span></span></span><span class="line"><span class="cl"><span class="s">subjectKeyIdentifier = hash
</span></span></span><span class="line"><span class="cl"><span class="s">authorityKeyIdentifier = keyid:always,issuer
</span></span></span><span class="line"><span class="cl"><span class="s">basicConstraints = critical, CA:true
</span></span></span><span class="line"><span class="cl"><span class="s">keyUsage = critical, digitalSignature, cRLSign, keyCertSign
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[usr_cert]
</span></span></span><span class="line"><span class="cl"><span class="s">basicConstraints = CA:FALSE
</span></span></span><span class="line"><span class="cl"><span class="s">nsCertType = client, email
</span></span></span><span class="line"><span class="cl"><span class="s">nsComment = &#34;Client Certificate&#34;
</span></span></span><span class="line"><span class="cl"><span class="s">subjectKeyIdentifier = hash
</span></span></span><span class="line"><span class="cl"><span class="s">authorityKeyIdentifier = keyid,issuer
</span></span></span><span class="line"><span class="cl"><span class="s">keyUsage = critical, nonRepudiation, digitalSignature, keyEncipherment
</span></span></span><span class="line"><span class="cl"><span class="s">extendedKeyUsage = clientAuth, emailProtection
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[server_cert]
</span></span></span><span class="line"><span class="cl"><span class="s">basicConstraints = CA:FALSE
</span></span></span><span class="line"><span class="cl"><span class="s">nsCertType = server
</span></span></span><span class="line"><span class="cl"><span class="s">nsComment = &#34;Server Certificate&#34;
</span></span></span><span class="line"><span class="cl"><span class="s">subjectKeyIdentifier = hash
</span></span></span><span class="line"><span class="cl"><span class="s">authorityKeyIdentifier = keyid,issuer:always
</span></span></span><span class="line"><span class="cl"><span class="s">keyUsage = critical, digitalSignature, keyEncipherment
</span></span></span><span class="line"><span class="cl"><span class="s">extendedKeyUsage = serverAuth
</span></span></span><span class="line"><span class="cl"><span class="s">EOF</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate CA private key</span>
</span></span><span class="line"><span class="cl">openssl genrsa -aes256 -out /etc/haproxy/ca/private/ca.key <span class="m">4096</span>
</span></span><span class="line"><span class="cl">chmod <span class="m">400</span> /etc/haproxy/ca/private/ca.key
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate CA certificate</span>
</span></span><span class="line"><span class="cl">openssl req -config /etc/haproxy/ca/openssl.cnf <span class="se">\
</span></span></span><span class="line"><span class="cl">  -key /etc/haproxy/ca/private/ca.key <span class="se">\
</span></span></span><span class="line"><span class="cl">  -new -x509 -days <span class="m">3650</span> -sha256 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -extensions v3_ca <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out /etc/haproxy/ca/certs/ca.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  -subj <span class="s2">&#34;/C=US/ST=State/L=City/O=MyOrg/CN=MyOrg CA&#34;</span>
</span></span></code></pre></div><h3 id="generate-server-certificate">Generate Server Certificate <a class="anchor" data-pagefind-ignore href="#generate-server-certificate" aria-label="Link to this section">#</a></h3>
<p>HAProxy presents this certificate to clients on the mTLS port. Clients verify it against the same CA, so they know they talk to the real API. The bind line loads certificate and key from one combined PEM file.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Generate server key</span>
</span></span><span class="line"><span class="cl">mkdir -p /etc/haproxy/certs
</span></span><span class="line"><span class="cl">openssl genrsa -out /etc/haproxy/certs/server.key <span class="m">2048</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate server CSR (clients such as Go and Python require the SAN)</span>
</span></span><span class="line"><span class="cl">openssl req -new <span class="se">\
</span></span></span><span class="line"><span class="cl">  -key /etc/haproxy/certs/server.key <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out /etc/haproxy/ca/csr/server.csr <span class="se">\
</span></span></span><span class="line"><span class="cl">  -subj <span class="s2">&#34;/CN=api.example.com&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -addext <span class="s2">&#34;subjectAltName=DNS:api.example.com&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Sign server certificate with CA</span>
</span></span><span class="line"><span class="cl">openssl ca -config /etc/haproxy/ca/openssl.cnf <span class="se">\
</span></span></span><span class="line"><span class="cl">  -extensions server_cert <span class="se">\
</span></span></span><span class="line"><span class="cl">  -days <span class="m">365</span> -notext -md sha256 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -in /etc/haproxy/ca/csr/server.csr <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out /etc/haproxy/certs/server.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  -batch
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create combined PEM for HAProxy</span>
</span></span><span class="line"><span class="cl">cat /etc/haproxy/certs/server.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">    /etc/haproxy/certs/server.key <span class="se">\
</span></span></span><span class="line"><span class="cl">    &gt; /etc/haproxy/certs/server.pem
</span></span><span class="line"><span class="cl">chmod <span class="m">600</span> /etc/haproxy/certs/server.pem
</span></span></code></pre></div><h3 id="generate-client-certificate">Generate Client Certificate <a class="anchor" data-pagefind-ignore href="#generate-client-certificate" aria-label="Link to this section">#</a></h3>
<p>Every client gets its own certificate, so you can authorize and revoke them one by one. The script takes a name (becomes the CN) and an optional OU (default <code>internal</code>); both are used in the ACLs later.</p>
<table>
	<thead>
			<tr>
					<th>Output</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>.key</code> + <code>.crt</code></td>
					<td>curl, Python, Go, Node.js</td>
			</tr>
			<tr>
					<td><code>.pem</code></td>
					<td>Tools that want certificate and key in one file</td>
			</tr>
			<tr>
					<td><code>.p12</code></td>
					<td>Browsers and Java; password <code>changeme</code>, change it</td>
			</tr>
	</tbody>
</table>
<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/generate-client-cert.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">CLIENT_NAME</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$1</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">CLIENT_OU</span><span class="o">=</span><span class="s2">&#34;</span><span class="si">${</span><span class="nv">2</span><span class="k">:-</span><span class="nv">internal</span><span class="si">}</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> -z <span class="s2">&#34;</span><span class="nv">$CLIENT_NAME</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="nb">echo</span> <span class="s2">&#34;Usage: </span><span class="nv">$0</span><span class="s2"> &lt;client-name&gt; [organizational-unit]&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="nb">exit</span> <span class="m">1</span>
</span></span><span class="line"><span class="cl"><span class="k">fi</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">CA_DIR</span><span class="o">=</span><span class="s2">&#34;/etc/haproxy/ca&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">OUTPUT_DIR</span><span class="o">=</span><span class="s2">&#34;/etc/haproxy/clients/</span><span class="nv">$CLIENT_NAME</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">mkdir -p <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</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"># Generate client key</span>
</span></span><span class="line"><span class="cl">openssl genrsa -out <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.key&#34;</span> <span class="m">2048</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate client CSR</span>
</span></span><span class="line"><span class="cl">openssl req -new <span class="se">\
</span></span></span><span class="line"><span class="cl">  -key <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.key&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out <span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/csr/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.csr&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -subj <span class="s2">&#34;/OU=</span><span class="nv">$CLIENT_OU</span><span class="s2">/CN=</span><span class="nv">$CLIENT_NAME</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"># Sign client certificate</span>
</span></span><span class="line"><span class="cl">openssl ca -config <span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/openssl.cnf&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -extensions usr_cert <span class="se">\
</span></span></span><span class="line"><span class="cl">  -days <span class="m">365</span> -notext -md sha256 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -in <span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/csr/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.csr&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.crt&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -batch
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create combined PEM (for applications that need it)</span>
</span></span><span class="line"><span class="cl">cat <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.crt&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.key&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    &gt; <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</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"># Create PKCS12 bundle (for browsers and some clients)</span>
</span></span><span class="line"><span class="cl">openssl pkcs12 -export <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.p12&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -inkey <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.key&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -in <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.crt&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -certfile <span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/certs/ca.crt&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -passout pass:changeme
</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;Client certificate generated in </span><span class="nv">$OUTPUT_DIR</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;Files: </span><span class="nv">$CLIENT_NAME</span><span class="s2">.key, </span><span class="nv">$CLIENT_NAME</span><span class="s2">.crt, </span><span class="nv">$CLIENT_NAME</span><span class="s2">.pem, </span><span class="nv">$CLIENT_NAME</span><span class="s2">.p12&#34;</span>
</span></span></code></pre></div><h2 id="basic-mtls-configuration">Basic mTLS Configuration <a class="anchor" data-pagefind-ignore href="#basic-mtls-configuration" aria-label="Link to this section">#</a></h2>
<p>Two bind options switch mTLS on:</p>
<ul>
<li><code>ca-file</code>: the CA that client certificates must be signed by.</li>
<li><code>verify</code>: <code>required</code> rejects the handshake without a valid certificate; <code>optional</code> lets it through and you decide in ACLs.</li>
</ul>
<table>
	<thead>
			<tr>
					<th>Mode</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>verify required</code></td>
					<td>Endpoints only certificate holders may reach</td>
			</tr>
			<tr>
					<td><code>verify optional</code></td>
					<td>One endpoint serving both anonymous and authenticated clients</td>
			</tr>
	</tbody>
</table>
<h3 id="required-mtls">Required mTLS <a class="anchor" data-pagefind-ignore href="#required-mtls" aria-label="Link to this section">#</a></h3>
<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
    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

frontend mtls_api
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt verify required
    
    # Client certificate is required - connections without valid cert are rejected
    default_backend api_servers

backend api_servers
    server api1 192.168.1.10:8080 check
    server api2 192.168.1.11:8080 check
</code></pre><h3 id="optional-mtls-certificate-if-available">Optional mTLS (Certificate if Available) <a class="anchor" data-pagefind-ignore href="#optional-mtls-certificate-if-available" aria-label="Link to this section">#</a></h3>
<p>Clients with a valid certificate go to <code>authenticated_api</code>, clients without one to <code>public_api</code>, and an invalid certificate gets a 403.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend mtls_optional
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt verify optional
    
    # Check if client provided valid certificate
    # (ssl_c_verify is also 0 when no certificate was sent, so combine it with ssl_fc_has_crt)
    acl client_cert_valid ssl_c_verify 0
    acl client_cert_provided ssl_fc_has_crt
    
    # Reject invalid certificates
    http-request deny if client_cert_provided !client_cert_valid
    
    # Route based on certificate status
    use_backend authenticated_api if client_cert_provided client_cert_valid
    use_backend public_api unless client_cert_provided

backend authenticated_api
    server api1 192.168.1.10:8080 check

backend public_api
    server public1 192.168.1.20:8080 check
</code></pre><h2 id="passing-client-certificate-info-to-backend">Passing Client Certificate Info to Backend <a class="anchor" data-pagefind-ignore href="#passing-client-certificate-info-to-backend" aria-label="Link to this section">#</a></h2>
<p>The backend sees plain HTTP from HAProxy, not the certificate. Add headers so the application knows which client called.</p>
<h3 id="certificate-details-as-headers">Certificate Details as Headers <a class="anchor" data-pagefind-ignore href="#certificate-details-as-headers" aria-label="Link to this section">#</a></h3>
<ul>
<li><code>ssl_c_s_dn(cn)</code>: the client name, the usual identity for application logic.</li>
<li><code>ssl_c_serial</code> / <code>ssl_c_sha1</code>: unique per certificate, useful for audit logs.</li>
<li><code>%{+Q}</code>: quotes the value, since DNs contain commas and spaces.</li>
</ul>
<p><code>set-header</code> overwrites any <code>X-Client-*</code> header a client sends itself, so clients cannot fake them.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend mtls_api
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt verify required
    
    # Client certificate subject (DN)
    http-request set-header X-Client-DN %{+Q}[ssl_c_s_dn]
    
    # Client certificate common name
    http-request set-header X-Client-CN %{+Q}[ssl_c_s_dn(cn)]
    
    # Certificate serial number
    http-request set-header X-Client-Serial %[ssl_c_serial,hex]
    
    # Certificate fingerprint (SHA1)
    http-request set-header X-Client-Fingerprint %[ssl_c_sha1,hex]
    
    # Certificate validity dates
    http-request set-header X-Client-NotBefore %[ssl_c_notbefore]
    http-request set-header X-Client-NotAfter %[ssl_c_notafter]
    
    # Issuer DN
    http-request set-header X-Client-Issuer %{+Q}[ssl_c_i_dn]
    
    # Verification status (0 = success)
    http-request set-header X-Client-Verify %[ssl_c_verify]
    
    default_backend api_servers
</code></pre><h3 id="full-certificate-as-header-base64">Full Certificate as Header (Base64) <a class="anchor" data-pagefind-ignore href="#full-certificate-as-header-base64" aria-label="Link to this section">#</a></h3>
<p>Use this when the application must parse the certificate itself, for example to read custom extensions.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend mtls_api
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt verify required
    
    # Pass entire certificate (DER format, base64 encoded)
    http-request set-header X-Client-Cert %[ssl_c_der,base64]
    
    default_backend api_servers
</code></pre><h2 id="certificate-based-authorization">Certificate-Based Authorization <a class="anchor" data-pagefind-ignore href="#certificate-based-authorization" aria-label="Link to this section">#</a></h2>
<p>A valid certificate proves who the client is, not what it may do. ACLs on certificate fields add authorization.</p>
<table>
	<thead>
			<tr>
					<th>Match on</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>CN</td>
					<td>Individual services or clients</td>
			</tr>
			<tr>
					<td>OU</td>
					<td>Groups of clients (internal, partner, admin)</td>
			</tr>
			<tr>
					<td>Fingerprint</td>
					<td>An explicit allowlist of exact certificates</td>
			</tr>
	</tbody>
</table>
<h3 id="route-by-client-cn">Route by Client CN <a class="anchor" data-pagefind-ignore href="#route-by-client-cn" aria-label="Link to this section">#</a></h3>
<p>Each named client gets its own backend; everyone else goes to <code>api_backend</code>.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend mtls_api
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt verify required
    
    # ACLs based on client certificate CN
    acl cn_admin ssl_c_s_dn(cn) -i admin-service
    acl cn_api ssl_c_s_dn(cn) -i api-client
    acl cn_monitoring ssl_c_s_dn(cn) -i monitoring
    
    # Route to different backends
    use_backend admin_backend if cn_admin
    use_backend monitoring_backend if cn_monitoring
    default_backend api_backend
</code></pre><h3 id="restrict-access-by-certificate-ou">Restrict Access by Certificate OU <a class="anchor" data-pagefind-ignore href="#restrict-access-by-certificate-ou" aria-label="Link to this section">#</a></h3>
<p>Paths are locked to a group: <code>/admin</code> only for the <code>administrators</code> OU, <code>/api/partner</code> only for <code>partner-api</code>.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend mtls_api
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt verify required
    
    # Check organizational unit
    acl ou_internal ssl_c_s_dn(ou) -i internal-services
    acl ou_partner ssl_c_s_dn(ou) -i partner-api
    acl ou_admin ssl_c_s_dn(ou) -i administrators
    
    # Restrict admin endpoints
    acl admin_path path_beg /admin
    http-request deny if admin_path !ou_admin
    
    # Partner access restrictions
    acl partner_path path_beg /api/partner
    http-request deny if partner_path !ou_partner
    
    default_backend api_servers
</code></pre><h3 id="whitelist-specific-certificates">Whitelist Specific Certificates <a class="anchor" data-pagefind-ignore href="#whitelist-specific-certificates" aria-label="Link to this section">#</a></h3>
<p>The strictest option: only certificates whose SHA1 fingerprint is in the file get through, even if the CA signed others.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend mtls_api
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt verify required
    
    # Define allowed certificate fingerprints
    acl allowed_cert ssl_c_sha1,hex -f /etc/haproxy/allowed-certs.txt
    
    # Reject certificates not in whitelist
    http-request deny unless allowed_cert
    
    default_backend api_servers
</code></pre><p>Create the whitelist file. A renewed certificate has a new fingerprint, so update the file when you reissue.</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/haproxy/allowed-certs.txt</span>
</span></span><span class="line"><span class="cl"><span class="c1"># One SHA1 fingerprint per line, uppercase hex without colons:</span>
</span></span><span class="line"><span class="cl"><span class="c1">#   openssl x509 -in client.crt -noout -fingerprint -sha1 | cut -d= -f2 | tr -d :</span>
</span></span><span class="line"><span class="cl">A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0
</span></span><span class="line"><span class="cl">9T8S7R6Q5P4O3N2M1L0K9J8I7H6G5F4E3D2C1B0A
</span></span></code></pre></div><h2 id="certificate-revocation">Certificate Revocation <a class="anchor" data-pagefind-ignore href="#certificate-revocation" aria-label="Link to this section">#</a></h2>
<p>A stolen or retired client certificate stays valid until it expires. A CRL lists revoked serial numbers; HAProxy rejects them during the handshake.</p>
<h3 id="using-crl-certificate-revocation-list">Using CRL (Certificate Revocation List) <a class="anchor" data-pagefind-ignore href="#using-crl-certificate-revocation-list" aria-label="Link to this section">#</a></h3>
<p>Revoke the certificate, regenerate the CRL, then load it with <code>crl-file</code> on the bind line.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Generate initial CRL</span>
</span></span><span class="line"><span class="cl">openssl ca -config /etc/haproxy/ca/openssl.cnf <span class="se">\
</span></span></span><span class="line"><span class="cl">  -gencrl -out /etc/haproxy/ca/crl/ca.crl
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Revoke a certificate</span>
</span></span><span class="line"><span class="cl">openssl ca -config /etc/haproxy/ca/openssl.cnf <span class="se">\
</span></span></span><span class="line"><span class="cl">  -revoke /etc/haproxy/clients/bad-client/bad-client.crt
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Regenerate CRL</span>
</span></span><span class="line"><span class="cl">openssl ca -config /etc/haproxy/ca/openssl.cnf <span class="se">\
</span></span></span><span class="line"><span class="cl">  -gencrl -out /etc/haproxy/ca/crl/ca.crl
</span></span></code></pre></div><p>HAProxy reads the CRL at startup, so reload after each change.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend mtls_api
    # HAProxy has no line continuation: keep the bind on one line
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt crl-file /etc/haproxy/ca/crl/ca.crl verify required
    
    default_backend api_servers
</code></pre><h3 id="automated-crl-updates">Automated CRL Updates <a class="anchor" data-pagefind-ignore href="#automated-crl-updates" aria-label="Link to this section">#</a></h3>
<p>A CRL expires after <code>default_crl_days</code> (30). An expired CRL makes HAProxy reject every client, so regenerate it on a schedule.</p>
<p>The CA key is encrypted, and cron cannot type its passphrase. Store the passphrase in a file that only root can read, so the script can pass it to openssl with <code>-passin</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Same passphrase as the one protecting ca.key</span>
</span></span><span class="line"><span class="cl">install -m <span class="m">0400</span> /dev/null /etc/haproxy/ca/private/ca.pass
</span></span><span class="line"><span class="cl"><span class="nb">read</span> -rsp <span class="s1">&#39;CA key passphrase: &#39;</span> P <span class="o">&amp;&amp;</span> <span class="nb">printf</span> <span class="s1">&#39;%s\n&#39;</span> <span class="s2">&#34;</span><span class="nv">$P</span><span class="s2">&#34;</span> &gt; /etc/haproxy/ca/private/ca.pass<span class="p">;</span> <span class="nb">unset</span> P<span class="p">;</span> <span class="nb">echo</span>
</span></span></code></pre></div><p>Anyone with root on this machine can now sign certificates with your CA, so keep the CA host locked down.</p>
<p>The script writes to a temporary file first, so a failed run never leaves HAProxy with a broken CRL.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># /usr/local/bin/update-crl.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">set</span> -euo pipefail
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">CA_DIR</span><span class="o">=</span><span class="s2">&#34;/etc/haproxy/ca&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">CRL_FILE</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/crl/ca.crl&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">PASS_FILE</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/private/ca.pass&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Regenerate CRL; if openssl fails the script stops here and HAProxy keeps the current CRL</span>
</span></span><span class="line"><span class="cl">openssl ca -config <span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/openssl.cnf&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -gencrl -passin <span class="s2">&#34;file:</span><span class="nv">$PASS_FILE</span><span class="s2">&#34;</span> -out <span class="s2">&#34;</span><span class="nv">$CRL_FILE</span><span class="s2">.new&#34;</span>
</span></span><span class="line"><span class="cl">mv <span class="s2">&#34;</span><span class="nv">$CRL_FILE</span><span class="s2">.new&#34;</span> <span class="s2">&#34;</span><span class="nv">$CRL_FILE</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"># Reload HAProxy</span>
</span></span><span class="line"><span class="cl">systemctl reload haproxy
</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">700</span> /usr/local/bin/update-crl.sh
</span></span></code></pre></div><p>Schedule with cron, in root&rsquo;s crontab (<code>crontab -e</code> as root):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Update CRL every hour</span>
</span></span><span class="line"><span class="cl"><span class="m">0</span> * * * * /usr/local/bin/update-crl.sh
</span></span></code></pre></div><h2 id="complete-production-configuration">Complete Production Configuration <a class="anchor" data-pagefind-ignore href="#complete-production-configuration" aria-label="Link to this section">#</a></h2>
<p>Everything combined. The layout:</p>
<table>
	<thead>
			<tr>
					<th>Frontend / listen</th>
					<th>Port</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>stats</code></td>
					<td>8404</td>
					<td>Stats page and Prometheus <code>/metrics</code></td>
			</tr>
			<tr>
					<td><code>public_https</code></td>
					<td>443</td>
					<td>Public site with a public certificate; <code>/api</code> is redirected to 8443</td>
			</tr>
			<tr>
					<td><code>mtls_api</code></td>
					<td>8443</td>
					<td>mTLS with CRL, identity headers, CN/OU authorization</td>
			</tr>
	</tbody>
</table>
<p>The authorization rules in <code>mtls_api</code>:</p>
<ul>
<li><code>/api/admin</code> only for CN <code>admin-service</code>.</li>
<li>CNs containing <code>readonly</code> cannot use POST, PUT, DELETE or PATCH.</li>
<li>Only OU <code>internal</code> or <code>partner</code> gets in at all; partners go to <code>partner_api</code>.</li>
</ul>
<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 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
    option forwardfor
    timeout connect 5s
    timeout client  50s
    timeout server  50s

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

# Public HTTPS (no client cert required)
frontend public_https
    # public.pem: your publicly trusted certificate (for example Let&#39;s Encrypt), not one from the internal CA
    bind *:443 ssl crt /etc/haproxy/certs/public.pem alpn h2,http/1.1
    
    # Route to mTLS frontend for API paths
    acl api_path path_beg /api
    use_backend mtls_redirect if api_path
    
    default_backend public_web

# mTLS API endpoint
frontend mtls_api
    bind *:8443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt crl-file /etc/haproxy/ca/crl/ca.crl verify required alpn h2,http/1.1
    
    # Log client certificate info
    capture request header X-Client-CN len 50
    log-format &#34;%ci:%cp [%tr] %ft %b/%s %ST %B %TR/%Tw/%Tc/%Tr/%Ta client_cn:%{+Q}[ssl_c_s_dn(cn)] %r&#34;
    
    # Add client info headers
    http-request set-header X-Client-CN %{+Q}[ssl_c_s_dn(cn)]
    http-request set-header X-Client-DN %{+Q}[ssl_c_s_dn]
    http-request set-header X-Client-Serial %[ssl_c_serial,hex]
    http-request set-header X-Client-Verify %[ssl_c_verify]
    http-request set-header X-Client-Fingerprint %[ssl_c_sha1,hex]
    
    # Certificate-based authorization
    acl cn_admin ssl_c_s_dn(cn) -i admin-service
    acl cn_readonly ssl_c_s_dn(cn) -m sub readonly
    acl ou_internal ssl_c_s_dn(ou) -i internal
    acl ou_partner ssl_c_s_dn(ou) -i partner
    
    # Path-based ACLs
    acl admin_path path_beg /api/admin
    acl write_method method POST PUT DELETE PATCH
    
    # Authorization rules
    http-request deny if admin_path !cn_admin
    http-request deny if write_method cn_readonly
    http-request deny if !ou_internal !ou_partner
    
    # Route based on certificate
    use_backend admin_api if cn_admin
    use_backend partner_api if ou_partner
    default_backend internal_api

# Redirect to mTLS port
backend mtls_redirect
    http-request redirect code 301 location https://%[req.hdr(Host)]:8443%[capture.req.uri]

backend public_web
    balance roundrobin
    server web1 192.168.1.10:8080 check
    server web2 192.168.1.11:8080 check

backend internal_api
    balance leastconn
    option httpchk GET /health
    http-check expect status 200
    server api1 192.168.1.20:8080 check
    server api2 192.168.1.21:8080 check

backend admin_api
    option httpchk GET /health
    server admin1 192.168.1.30:8080 check

backend partner_api
    balance roundrobin
    option httpchk GET /health
    server partner1 192.168.1.40:8080 check
    server partner2 192.168.1.41:8080 check
</code></pre><h2 id="testing-mtls">Testing mTLS <a class="anchor" data-pagefind-ignore href="#testing-mtls" aria-label="Link to this section">#</a></h2>
<p>Test both sides: a request with a certificate must work, one without must fail.</p>
<h3 id="test-with-curl">Test with curl <a class="anchor" data-pagefind-ignore href="#test-with-curl" 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"># Test with client certificate</span>
</span></span><span class="line"><span class="cl">curl -v <span class="se">\
</span></span></span><span class="line"><span class="cl">  --cert /etc/haproxy/clients/api-client/api-client.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  --key /etc/haproxy/clients/api-client/api-client.key <span class="se">\
</span></span></span><span class="line"><span class="cl">  --cacert /etc/haproxy/ca/certs/ca.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  https://api.example.com:8443/api/status
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test with combined PEM</span>
</span></span><span class="line"><span class="cl">curl -v <span class="se">\
</span></span></span><span class="line"><span class="cl">  --cert /etc/haproxy/clients/api-client/api-client.pem <span class="se">\
</span></span></span><span class="line"><span class="cl">  --cacert /etc/haproxy/ca/certs/ca.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  https://api.example.com:8443/api/status
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test without certificate (should fail)</span>
</span></span><span class="line"><span class="cl">curl -v <span class="se">\
</span></span></span><span class="line"><span class="cl">  --cacert /etc/haproxy/ca/certs/ca.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  https://api.example.com:8443/api/status
</span></span></code></pre></div><h3 id="test-with-openssl">Test with openssl <a class="anchor" data-pagefind-ignore href="#test-with-openssl" aria-label="Link to this section">#</a></h3>
<p><code>s_client</code> shows the handshake: the server certificate, whether HAProxy asked for a client certificate, and the verify result.</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"># Connect and show certificate exchange</span>
</span></span><span class="line"><span class="cl">openssl s_client <span class="se">\
</span></span></span><span class="line"><span class="cl">  -connect api.example.com:8443 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -cert /etc/haproxy/clients/api-client/api-client.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  -key /etc/haproxy/clients/api-client/api-client.key <span class="se">\
</span></span></span><span class="line"><span class="cl">  -CAfile /etc/haproxy/ca/certs/ca.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  -verify_return_error
</span></span></code></pre></div><h2 id="client-configuration-examples">Client Configuration Examples <a class="anchor" data-pagefind-ignore href="#client-configuration-examples" aria-label="Link to this section">#</a></h2>
<p>Every client needs the same three files: its certificate, its key, and the CA certificate to verify HAProxy.</p>
<h3 id="python-requests">Python requests <a class="anchor" data-pagefind-ignore href="#python-requests" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">requests</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">response</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">    <span class="s1">&#39;https://api.example.com:8443/api/data&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="n">cert</span><span class="o">=</span><span class="p">(</span><span class="s1">&#39;/path/to/client.crt&#39;</span><span class="p">,</span> <span class="s1">&#39;/path/to/client.key&#39;</span><span class="p">),</span>
</span></span><span class="line"><span class="cl">    <span class="n">verify</span><span class="o">=</span><span class="s1">&#39;/path/to/ca.crt&#39;</span>
</span></span><span class="line"><span class="cl"><span class="p">)</span>
</span></span></code></pre></div><h3 id="nodejs">Node.js <a class="anchor" data-pagefind-ignore href="#nodejs" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-javascript" data-lang="javascript"><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">https</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;https&#39;</span><span class="p">);</span>
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">fs</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;fs&#39;</span><span class="p">);</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">options</span> <span class="o">=</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nx">hostname</span><span class="o">:</span> <span class="s1">&#39;api.example.com&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">port</span><span class="o">:</span> <span class="mi">8443</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">path</span><span class="o">:</span> <span class="s1">&#39;/api/data&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">method</span><span class="o">:</span> <span class="s1">&#39;GET&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">cert</span><span class="o">:</span> <span class="nx">fs</span><span class="p">.</span><span class="nx">readFileSync</span><span class="p">(</span><span class="s1">&#39;/path/to/client.crt&#39;</span><span class="p">),</span>
</span></span><span class="line"><span class="cl">  <span class="nx">key</span><span class="o">:</span> <span class="nx">fs</span><span class="p">.</span><span class="nx">readFileSync</span><span class="p">(</span><span class="s1">&#39;/path/to/client.key&#39;</span><span class="p">),</span>
</span></span><span class="line"><span class="cl">  <span class="nx">ca</span><span class="o">:</span> <span class="nx">fs</span><span class="p">.</span><span class="nx">readFileSync</span><span class="p">(</span><span class="s1">&#39;/path/to/ca.crt&#39;</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="kr">const</span> <span class="nx">req</span> <span class="o">=</span> <span class="nx">https</span><span class="p">.</span><span class="nx">request</span><span class="p">(</span><span class="nx">options</span><span class="p">,</span> <span class="p">(</span><span class="nx">res</span><span class="p">)</span> <span class="p">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="c1">// Handle response
</span></span></span><span class="line"><span class="cl"><span class="p">});</span>
</span></span></code></pre></div><h3 id="go">Go <a class="anchor" data-pagefind-ignore href="#go" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go"><span class="line"><span class="cl"><span class="kn">package</span><span class="w"> </span><span class="nx">main</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="kn">import</span><span class="w"> </span><span class="p">(</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="s">&#34;crypto/tls&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="s">&#34;crypto/x509&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="s">&#34;io/ioutil&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="s">&#34;net/http&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="kd">func</span><span class="w"> </span><span class="nf">main</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nx">cert</span><span class="p">,</span><span class="w"> </span><span class="nx">_</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="nx">tls</span><span class="p">.</span><span class="nf">LoadX509KeyPair</span><span class="p">(</span><span class="s">&#34;client.crt&#34;</span><span class="p">,</span><span class="w"> </span><span class="s">&#34;client.key&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nx">caCert</span><span class="p">,</span><span class="w"> </span><span class="nx">_</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="nx">ioutil</span><span class="p">.</span><span class="nf">ReadFile</span><span class="p">(</span><span class="s">&#34;ca.crt&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nx">caCertPool</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="nx">x509</span><span class="p">.</span><span class="nf">NewCertPool</span><span class="p">()</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nx">caCertPool</span><span class="p">.</span><span class="nf">AppendCertsFromPEM</span><span class="p">(</span><span class="nx">caCert</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nx">client</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="o">&amp;</span><span class="nx">http</span><span class="p">.</span><span class="nx">Client</span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nx">Transport</span><span class="p">:</span><span class="w"> </span><span class="o">&amp;</span><span class="nx">http</span><span class="p">.</span><span class="nx">Transport</span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nx">TLSClientConfig</span><span class="p">:</span><span class="w"> </span><span class="o">&amp;</span><span class="nx">tls</span><span class="p">.</span><span class="nx">Config</span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="nx">Certificates</span><span class="p">:</span><span class="w"> </span><span class="p">[]</span><span class="nx">tls</span><span class="p">.</span><span class="nx">Certificate</span><span class="p">{</span><span class="nx">cert</span><span class="p">},</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="nx">RootCAs</span><span class="p">:</span><span class="w">      </span><span class="nx">caCertPool</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="p">},</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">},</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nx">resp</span><span class="p">,</span><span class="w"> </span><span class="nx">_</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="nx">client</span><span class="p">.</span><span class="nf">Get</span><span class="p">(</span><span class="s">&#34;https://api.example.com:8443/api/data&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c1">// Handle response</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<h3 id="common-errors">Common Errors <a class="anchor" data-pagefind-ignore href="#common-errors" aria-label="Link to this section">#</a></h3>
<table>
	<thead>
			<tr>
					<th>Error</th>
					<th>Cause</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>tlsv1 alert unknown ca</code></td>
					<td>Client certificate not signed by the CA in <code>ca-file</code></td>
			</tr>
			<tr>
					<td><code>SSL certificate verify failed</code></td>
					<td>CA certificate mismatch</td>
			</tr>
			<tr>
					<td><code>tlsv13 alert certificate required</code> (TLS 1.2: handshake failure)</td>
					<td>Client didn&rsquo;t provide certificate when required</td>
			</tr>
			<tr>
					<td><code>ssl/tls alert certificate revoked</code></td>
					<td>Certificate is in CRL</td>
			</tr>
	</tbody>
</table>
<h3 id="debug-commands">Debug Commands <a class="anchor" data-pagefind-ignore href="#debug-commands" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Verify certificate chain</span>
</span></span><span class="line"><span class="cl">openssl verify -CAfile ca.crt client.crt
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check certificate details</span>
</span></span><span class="line"><span class="cl">openssl x509 -in client.crt -text -noout
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check CRL contents</span>
</span></span><span class="line"><span class="cl">openssl crl -in ca.crl -text -noout
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test SSL connection with debug</span>
</span></span><span class="line"><span class="cl">openssl s_client -connect api.example.com:8443 -debug
</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>Protect the CA key.</strong> Whoever has it can mint valid client certificates. Keep it encrypted and the CA host locked down.</li>
<li><strong>Short client lifetimes.</strong> 365 days here; shorter limits the damage of a leaked key.</li>
<li><strong>Keep the CRL fresh.</strong> Run the hourly update; an expired CRL locks everyone out.</li>
<li><strong>Do not trust client headers.</strong> Always overwrite <code>X-Client-*</code> in HAProxy, as above, and make backends reachable only through HAProxy.</li>
<li><strong>Change the PKCS12 password</strong> from <code>changeme</code> in the client script.</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-mtls" rel="noopener">pderuiter/blog-haproxy-mtls</a>. It creates an HAProxy VM on Proxmox, builds the internal CA with server and client certificates, and configures the complete production configuration from this post with certificate-based authorization and the hourly CRL update; put the CA passphrase in <code>vault.yml</code>, run <code>terraform apply</code>, then <code>ansible-playbook site.yml</code>.</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: the HAProxy Data Plane API for dynamic configuration management.</p>
<h2 id="summary">Summary <a class="anchor" data-pagefind-ignore href="#summary" aria-label="Link to this section">#</a></h2>
<p>Key points for HAProxy mTLS:</p>
<ul>
<li>Use <code>verify required</code> for mandatory client certificates</li>
<li>Use <code>verify optional</code> for mixed authentication</li>
<li>Pass certificate details to backends via headers</li>
<li>Implement authorization based on CN, OU, or fingerprint</li>
<li>Maintain CRL for certificate revocation</li>
<li>Generate unique certificates for each client/service</li>
<li>Test thoroughly with curl and openssl</li>
</ul>
<p>mTLS gives strong mutual authentication without passwords, a good fit for service-to-service communication and API access.</p>
]]></content:encoded></item><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><item><title>Securing DNS Traffic with DNS over TLS (DoT) on BIND</title><link>https://blog.bsdserver.nl/securing-dns-traffic-with-dns-over-tls-dot-on-bind/</link><guid isPermaLink="false">693b6eb479eb54000160a5a5</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:24:04 +0000</pubDate><description>Traditional DNS queries travel in plaintext, exposing your browsing habits to network observers.</description><category>BIND</category><category>DNS</category><category>DNS over TLS</category><category>TLS</category><category>Security</category><category>Encryption</category><category>Homelab</category><category>Linux</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/securing-dns-with-DoT.png" medium="image"/><content:encoded><![CDATA[<p>Traditional DNS queries travel in plaintext, exposing your browsing habits to network observers. Anyone on the path can read them, and can change the answers.</p>
<p>DNS over TLS (DoT) encrypts DNS traffic between clients and resolvers, providing privacy and preventing tampering. This post covers implementing DoT on BIND 9 in two roles: as a DoT server for your clients, and as a forwarder that sends its own queries upstream over DoT.</p>
<h2 id="why-dot">Why DoT? <a class="anchor" data-pagefind-ignore href="#why-dot" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Privacy</strong>: ISPs and network observers cannot see DNS queries</li>
<li><strong>Integrity</strong>: Prevents DNS query/response manipulation</li>
<li><strong>Authentication</strong>: Server identity verified via TLS certificates</li>
<li><strong>Compliance</strong>: Helps meet data protection requirements</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> when DNS crosses networks you do not trust: Wi-Fi, branch links, the path to a public resolver, or mobile clients using your resolver.</li>
<li><strong>Skip it</strong> on a trusted LAN segment between a client and a resolver next to it. It adds certificates to manage and TCP connections to carry, for little gain.</li>
</ul>
<h3 id="dot-vs-doh">DoT vs DoH <a class="anchor" data-pagefind-ignore href="#dot-vs-doh" aria-label="Link to this section">#</a></h3>
<p>Both encrypt DNS with TLS. The difference is the port, and with it who can see and block the traffic.</p>
<table>
	<thead>
			<tr>
					<th>Feature</th>
					<th>DNS over TLS (DoT)</th>
					<th>DNS over HTTPS (DoH)</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Port</td>
					<td>853 (dedicated)</td>
					<td>443 (shared with HTTPS)</td>
			</tr>
			<tr>
					<td>Protocol</td>
					<td>TLS directly</td>
					<td>HTTP/2 over TLS</td>
			</tr>
			<tr>
					<td>Blockable</td>
					<td>Easily (port 853)</td>
					<td>Harder to distinguish</td>
			</tr>
			<tr>
					<td>Performance</td>
					<td>Better (simpler)</td>
					<td>Slightly more overhead</td>
			</tr>
			<tr>
					<td>Use case</td>
					<td>Network operators</td>
					<td>End users/browsers</td>
			</tr>
	</tbody>
</table>
<h2 id="how-it-works">How it works <a class="anchor" data-pagefind-ignore href="#how-it-works" aria-label="Link to this section">#</a></h2>
<p>DoT wraps standard DNS queries in TLS encryption:</p>
<ol>
<li>Client initiates TLS connection to port 853</li>
<li>TLS handshake establishes encrypted channel</li>
<li>DNS queries and responses flow encrypted</li>
<li>Connection may persist for multiple queries</li>
</ol>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>DoT client</td>
					<td>Laptop, phone, or a local stub (systemd-resolved, Stubby)</td>
					<td>Opens TLS to port 853, checks the server certificate, sends queries.</td>
			</tr>
			<tr>
					<td>BIND DoT listener</td>
					<td>Your resolver</td>
					<td>Terminates TLS with the <code>tls</code> block&rsquo;s certificate and answers as usual.</td>
			</tr>
			<tr>
					<td>BIND DoT forwarder (optional)</td>
					<td>Your resolver</td>
					<td>Sends its own queries to an upstream DoT resolver and checks that server&rsquo;s certificate.</td>
			</tr>
			<tr>
					<td>Upstream resolver</td>
					<td>Cloudflare, Google, Quad9</td>
					<td>Resolves the queries you forward.</td>
			</tr>
	</tbody>
</table>
<p>The flow: client → TLS on 853 → BIND → cache, or recursion / DoT forwarder → answer back over the same TLS connection.</p>
<h2 id="prerequisites">Prerequisites <a class="anchor" data-pagefind-ignore href="#prerequisites" aria-label="Link to this section">#</a></h2>
<p>Before configuring DoT, ensure you have:</p>
<ol>
<li>BIND 9.18+ (native DoT listener; forwarding over DoT needs BIND 9.20+) or BIND with stunnel/nginx</li>
<li>Valid TLS certificate (Let&rsquo;s Encrypt works well)</li>
<li>Port 853 accessible through firewall</li>
<li>A working recursive resolver setup</li>
</ol>
<h2 id="native-dot-in-bind-918">Native DoT in BIND 9.18+ <a class="anchor" data-pagefind-ignore href="#native-dot-in-bind-918" aria-label="Link to this section">#</a></h2>
<p>BIND 9.18 and later include native DNS over TLS support (it was developed in the 9.17 development branch). No proxy is needed: a named <code>tls</code> block holds the certificate, and <code>listen-on port 853 tls &lt;name&gt;</code> opens the listener.</p>
<h3 id="basic-dot-listener-configuration">Basic DoT Listener Configuration <a class="anchor" data-pagefind-ignore href="#basic-dot-listener-configuration" aria-label="Link to this section">#</a></h3>
<p>This keeps the plain listener on port 53 and adds a TLS listener on 853 next to it.</p>
<ul>
<li><code>listen-on port 853 tls local-tls</code>: the DoT listener, using the <code>tls local-tls</code> block below.</li>
<li><code>tcp-clients</code>: maximum concurrent TCP connections, DoT included. Raise it, because every DoT client holds a connection open.</li>
<li><code>tcp-keepalive-timeout</code>: how long an idle connection stays open for clients that use EDNS keepalive. In units of 100 ms.</li>
<li><code>dhparam-file</code>: optional, only used by DHE cipher suites.</li>
<li><code>protocols</code> and <code>ciphers</code>: TLS 1.2 and 1.3 only, with ECDHE suites for forward secrecy.</li>
<li><code>prefer-server-ciphers</code>: the server&rsquo;s cipher order wins over the client&rsquo;s.</li>
<li><code>session-tickets</code>: lets clients resume a TLS session without a full handshake.</li>
</ul>
<pre tabindex="0"><code class="language-named" data-lang="named">// /etc/bind/named.conf.options

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

logging {
    channel tls_log {
        file &#34;/var/log/named/tls.log&#34; versions 5 size 10m;
        severity info;
        print-time yes;
        print-category yes;
    };
    category network { tls_log; };
};
</code></pre><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<h3 id="test-dot-connectivity">Test DoT Connectivity <a class="anchor" data-pagefind-ignore href="#test-dot-connectivity" aria-label="Link to this section">#</a></h3>
<p>Start from the client: does a DoT query work, and what does the TLS handshake show?</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Test with kdig</span>
</span></span><span class="line"><span class="cl">kdig +tls @dns.example.com example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test with openssl</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> -e <span class="s2">&#34;\x00\x1e\x00\x00\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00\x07example\x03com\x00\x00\x01\x00\x01&#34;</span> <span class="p">|</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    openssl s_client -connect dns.example.com:853 -quiet
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Verbose TLS handshake</span>
</span></span><span class="line"><span class="cl">openssl s_client -connect dns.example.com:853 -status -tlsextdebug
</span></span></code></pre></div><h3 id="common-issues">Common Issues <a class="anchor" data-pagefind-ignore href="#common-issues" aria-label="Link to this section">#</a></h3>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Likely cause</th>
					<th>Check</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Client reports a certificate error</td>
					<td>Expired certificate, missing intermediate, or wrong name</td>
					<td>Certificate commands below</td>
			</tr>
			<tr>
					<td>BIND does not start after adding <code>tls</code></td>
					<td>BIND cannot read the key or certificate</td>
					<td>Permission commands below</td>
			</tr>
			<tr>
					<td>Connection refused on 853</td>
					<td>No listener, or the firewall drops it</td>
					<td>Connection commands below</td>
			</tr>
			<tr>
					<td>SERVFAIL with DoT forwarding</td>
					<td><code>remote-hostname</code> does not match an upstream&rsquo;s certificate</td>
					<td>One <code>tls</code> block per provider</td>
			</tr>
	</tbody>
</table>
<p><strong>Certificate errors:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check certificate validity</span>
</span></span><span class="line"><span class="cl">openssl x509 -in /etc/bind/tls/cert.pem -text -noout <span class="p">|</span> grep -A2 Validity
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Verify certificate chain (cert.pem is the full chain, pass it as -untrusted for the intermediate)</span>
</span></span><span class="line"><span class="cl">openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt -untrusted /etc/bind/tls/cert.pem /etc/bind/tls/cert.pem
</span></span></code></pre></div><p><strong>Permission errors:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Ensure BIND can read certificates</span>
</span></span><span class="line"><span class="cl">ls -la /etc/bind/tls/
</span></span><span class="line"><span class="cl">chown bind:bind /etc/bind/tls/*.pem
</span></span><span class="line"><span class="cl">chmod <span class="m">640</span> /etc/bind/tls/*.pem
</span></span></code></pre></div><p><strong>Connection refused:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check if BIND is listening on 853</span>
</span></span><span class="line"><span class="cl">ss -tlnp <span class="p">|</span> grep <span class="m">853</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check firewall</span>
</span></span><span class="line"><span class="cl">iptables -L INPUT -n <span class="p">|</span> grep <span class="m">853</span>
</span></span></code></pre></div><h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Use valid certificates</strong>: self-signed certificates don&rsquo;t provide authentication.</li>
<li><strong>Enable DNSSEC</strong>: DoT encrypts transport, DNSSEC authenticates content.</li>
<li><strong>Restrict TLS versions</strong>: only allow TLS 1.2 and 1.3.</li>
<li><strong>Monitor certificate expiry</strong>: set up alerts before certificates expire.</li>
<li><strong>Use strong cipher suites</strong>: prefer ECDHE for forward secrecy.</li>
<li><strong>Rate limit connections</strong>: prevent DoS attacks on port 853.</li>
<li><strong>Log TLS events</strong>: monitor for connection failures and attacks.</li>
<li><strong>Mind <code>forward first</code></strong>: when the DoT forwarders fail, queries leave unencrypted.</li>
</ul>
<h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub: <a href="https://github.com/pderuiter/blog-bind-dot-secure" rel="noopener">pderuiter/blog-bind-dot-secure</a>. It creates an Ubuntu 24.04 VM on Proxmox and configures BIND with the DoT listener from the complete configuration above, with optional DoT forwarding to Cloudflare (BIND 9.20 from the ISC packages) and the nftables rate limit; run <code>terraform apply</code> and then <code>ansible-playbook site.yml</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>With BIND 9.18+ the DoT listener is native; DoT forwarding needs 9.20+. On older versions, stunnel does the TLS for BIND.</p>
<p>Key takeaways:</p>
<ul>
<li>Use valid TLS certificates from a trusted CA</li>
<li>Enable both server-side DoT (for clients) and client-side DoT (for upstream forwarding)</li>
<li>Set <code>remote-hostname</code> per upstream provider</li>
<li>Monitor and maintain certificate renewals</li>
</ul>
<p>The next post will cover DNS over HTTPS (DoH), which provides similar encryption using HTTPS and is increasingly supported by browsers and applications.</p>
]]></content:encoded></item><item><title>Signing Your DNS Zones with DNSSEC on BIND Authoritative Servers</title><link>https://blog.bsdserver.nl/signing-your-dns-zones-with-dnssec-on-bind-authoritative-servers/</link><guid isPermaLink="false">693b6e4179eb54000160a599</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:22:09 +0000</pubDate><description>After configuring DNSSEC validation on your resolvers, the next step is signing your own authoritative zones.</description><category>BIND</category><category>DNS</category><category>DNSSEC</category><category>Security</category><category>Homelab</category><category>Linux</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/bind-dnssec.png" medium="image"/><content:encoded><![CDATA[<p>After configuring DNSSEC validation on your resolvers, the next step is signing your own authoritative zones. Without signatures, a validating resolver has nothing to check: your records can still be forged in transit.</p>
<p>This post signs zones on a BIND authoritative server. It covers key types and algorithms, a manual signing run to show the moving parts, automated signing with <code>dnssec-policy</code>, publishing the DS record, and key rollovers.</p>
<h2 id="why-sign-your-zones">Why sign your zones? <a class="anchor" data-pagefind-ignore href="#why-sign-your-zones" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Authentic answers</strong>: validating resolvers can prove your records came from you, unmodified.</li>
<li><strong>Completes the chain of trust</strong>: the DS record in the parent zone links your zone to the root.</li>
<li><strong>Enables DNSSEC-based features</strong>: records like TLSA (DANE) and SSHFP are only trusted when signed.</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> for public zones you control, where your registrar supports DS records.</li>
<li><strong>Skip it</strong> (for now) if nobody can monitor signature expiry or handle a KSK rollover. An expired signature takes the whole zone offline for validating resolvers, which is worse than no DNSSEC.</li>
</ul>
<h2 id="how-it-works">How it works <a class="anchor" data-pagefind-ignore href="#how-it-works" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Lives in</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>KSK (Key Signing Key)</td>
					<td>Your zone</td>
					<td>Signs the DNSKEY RRset (the zone&rsquo;s public keys)</td>
			</tr>
			<tr>
					<td>ZSK (Zone Signing Key)</td>
					<td>Your zone</td>
					<td>Signs all other records</td>
			</tr>
			<tr>
					<td>RRSIG records</td>
					<td>Your zone</td>
					<td>The signatures, one per record set</td>
			</tr>
			<tr>
					<td>NSEC / NSEC3</td>
					<td>Your zone</td>
					<td>Prove that a name or type does not exist</td>
			</tr>
			<tr>
					<td>DS record</td>
					<td>Parent zone</td>
					<td>Hash of your KSK; links your zone into the chain of trust</td>
			</tr>
	</tbody>
</table>
<p>The flow: resolver trusts the parent → parent&rsquo;s DS matches your KSK → KSK signs your DNSKEY set → ZSK signs your records → answer validated.</p>
<h3 id="key-signing-key-ksk">Key Signing Key (KSK) <a class="anchor" data-pagefind-ignore href="#key-signing-key-ksk" aria-label="Link to this section">#</a></h3>
<ul>
<li>Signs the DNSKEY RRset (the zone&rsquo;s public keys)</li>
<li>Longer lifetime (typically 1-2 years)</li>
<li>Larger key size for stronger security</li>
<li>Its hash (DS record) is published in the parent zone</li>
</ul>
<h3 id="zone-signing-key-zsk">Zone Signing Key (ZSK) <a class="anchor" data-pagefind-ignore href="#zone-signing-key-zsk" aria-label="Link to this section">#</a></h3>
<ul>
<li>Signs all other records in the zone</li>
<li>Shorter lifetime (typically 1-3 months)</li>
<li>Smaller key size for performance</li>
<li>Rolled more frequently</li>
</ul>
<p>The split exists because a KSK change needs your registrar (a new DS record), while a ZSK change does not. Keeping the KSK stable means you can roll the ZSK as often as you like without touching the parent.</p>
<h2 id="choosing-dnssec-algorithms">Choosing DNSSEC Algorithms <a class="anchor" data-pagefind-ignore href="#choosing-dnssec-algorithms" aria-label="Link to this section">#</a></h2>
<p>Modern BIND supports several algorithms:</p>
<table>
	<thead>
			<tr>
					<th>Algorithm</th>
					<th>Number</th>
					<th>Recommendation</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>RSASHA256</td>
					<td>8</td>
					<td>Good, widely supported</td>
			</tr>
			<tr>
					<td>RSASHA512</td>
					<td>10</td>
					<td>Good, wider margins</td>
			</tr>
			<tr>
					<td>ECDSAP256SHA256</td>
					<td>13</td>
					<td>Recommended, smaller keys</td>
			</tr>
			<tr>
					<td>ECDSAP384SHA384</td>
					<td>14</td>
					<td>Strong, larger signatures</td>
			</tr>
			<tr>
					<td>ED25519</td>
					<td>15</td>
					<td>Best, smallest signatures</td>
			</tr>
	</tbody>
</table>
<p>For new deployments, use <strong>ECDSAP256SHA256 (13)</strong> or <strong>ED25519 (15)</strong> for best performance and security. Smaller signatures keep responses under the UDP size limit.</p>
<h2 id="manual-signing-or-dnssec-policy">Manual signing or dnssec-policy? <a class="anchor" data-pagefind-ignore href="#manual-signing-or-dnssec-policy" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Approach</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Manual (<code>dnssec-keygen</code> + <code>dnssec-signzone</code>)</td>
					<td>Understanding the mechanics, or offline signing. You re-sign before signatures expire and run rollovers yourself.</td>
			</tr>
			<tr>
					<td><code>dnssec-policy</code> + inline signing</td>
					<td>Production. BIND generates keys, signs, re-signs and rolls the ZSK automatically.</td>
			</tr>
	</tbody>
</table>
<p>The manual steps below show what BIND automates. If you only want a working setup, skip to <a href="#automated-dnssec-with-dnssec-policy">Automated DNSSEC with dnssec-policy</a>.</p>
<h2 id="manual-dnssec-configuration">Manual DNSSEC Configuration <a class="anchor" data-pagefind-ignore href="#manual-dnssec-configuration" aria-label="Link to this section">#</a></h2>
<h3 id="generating-keys-manually">Generating Keys Manually <a class="anchor" data-pagefind-ignore href="#generating-keys-manually" aria-label="Link to this section">#</a></h3>
<p>First create a key directory that only BIND can read. The private keys in it can sign anything for your zone.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">mkdir -p /var/cache/bind/keys
</span></span><span class="line"><span class="cl">chown bind:bind /var/cache/bind/keys
</span></span><span class="line"><span class="cl">chmod <span class="m">700</span> /var/cache/bind/keys
</span></span></code></pre></div><p>Generate the KSK. <code>-f KSK</code> sets the KSK flag; <code>-n ZONE</code> marks it as a zone key.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nb">cd</span> /var/cache/bind/keys
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate KSK with ECDSAP256SHA256</span>
</span></span><span class="line"><span class="cl">dnssec-keygen -a ECDSAP256SHA256 -f KSK -n ZONE example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Or with RSA (2048-bit minimum, 4096 recommended for KSK)</span>
</span></span><span class="line"><span class="cl">dnssec-keygen -a RSASHA256 -b <span class="m">4096</span> -f KSK -n ZONE example.com
</span></span></code></pre></div><p>Generate the ZSK (same command, without <code>-f KSK</code>):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Generate ZSK with ECDSAP256SHA256</span>
</span></span><span class="line"><span class="cl">dnssec-keygen -a ECDSAP256SHA256 -n ZONE example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Or with RSA (2048-bit)</span>
</span></span><span class="line"><span class="cl">dnssec-keygen -a RSASHA256 -b <span class="m">2048</span> -n ZONE example.com
</span></span></code></pre></div><p>This creates two files per key:</p>
<ul>
<li><code>Kexample.com.+013+12345.key</code> - Public key (DNSKEY record)</li>
<li><code>Kexample.com.+013+12345.private</code> - Private key</li>
</ul>
<p>The <code>013</code> in the name is the algorithm number; <code>12345</code> is the key tag.</p>
<h3 id="manual-zone-signing">Manual Zone Signing <a class="anchor" data-pagefind-ignore href="#manual-zone-signing" aria-label="Link to this section">#</a></h3>
<p>Add the public keys to the zone with <code>$INCLUDE</code>, so the DNSKEY records are part of what gets signed:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-dns" data-lang="dns"><span class="line"><span class="cl"><span class="c">; /var/cache/bind/zones/db.example.com</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="na">$TTL</span><span class="w"> </span><span class="sc">86400</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="na">$INCLUDE</span><span class="w"> </span><span class="err">/var/cache/bind/keys/</span><span class="nc">Kexample.com.</span><span class="err">+</span><span class="sc">013</span><span class="err">+</span><span class="sc">12345</span><span class="err">.key</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="na">$INCLUDE</span><span class="w"> </span><span class="err">/var/cache/bind/keys/</span><span class="nc">Kexample.com.</span><span class="err">+</span><span class="sc">013</span><span class="err">+</span><span class="sc">67890</span><span class="err">.key</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">@</span><span class="w">   </span><span class="k">IN</span><span class="w">  </span><span class="k">SOA</span><span class="w"> </span><span class="py">ns1.example.com. admin.example.com. </span><span class="p">(</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="sc">2024011001</span><span class="w">  </span><span class="c">; Serial</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="sc">3600</span><span class="w">        </span><span class="c">; Refresh</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="sc">1800</span><span class="w">        </span><span class="c">; Retry</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="sc">604800</span><span class="w">      </span><span class="c">; Expire</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="sc">86400</span><span class="w"> </span><span class="p">)</span><span class="w">     </span><span class="c">; Minimum TTL</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">IN</span><span class="w">  </span><span class="k">NS</span><span class="w">  </span><span class="py">ns1.example.com.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">IN</span><span class="w">  </span><span class="k">NS</span><span class="w">  </span><span class="py">ns2.example.com.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">IN</span><span class="w">  </span><span class="k">MX</span><span class="w">  </span><span class="sc">10</span><span class="w"> </span><span class="py">mail.example.com.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">IN</span><span class="w">  </span><span class="k">A</span><span class="w">   </span><span class="mi">192.168.1.10</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">ns1</span><span class="w"> </span><span class="k">IN</span><span class="w">  </span><span class="k">A</span><span class="w">   </span><span class="mi">192.168.1.1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">ns2</span><span class="w"> </span><span class="k">IN</span><span class="w">  </span><span class="k">A</span><span class="w">   </span><span class="mi">192.168.1.2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">mail</span><span class="w"> </span><span class="k">IN</span><span class="w"> </span><span class="k">A</span><span class="w">   </span><span class="mi">192.168.1.20</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">www</span><span class="w"> </span><span class="k">IN</span><span class="w">  </span><span class="k">A</span><span class="w">   </span><span class="mi">192.168.1.10</span><span class="w">
</span></span></span></code></pre></div><p>Then sign the zone:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Sign zone with NSEC3 (no salt, 0 iterations as per RFC 9276)</span>
</span></span><span class="line"><span class="cl">dnssec-signzone -3 - <span class="se">\
</span></span></span><span class="line"><span class="cl">    -N INCREMENT -o example.com -t <span class="se">\
</span></span></span><span class="line"><span class="cl">    -K /var/cache/bind/keys <span class="se">\
</span></span></span><span class="line"><span class="cl">    /var/cache/bind/zones/db.example.com
</span></span></code></pre></div><ul>
<li><code>-3 -</code>: use NSEC3 with no salt.</li>
<li><code>-N INCREMENT</code>: increase the SOA serial so slave servers pick up the signed version.</li>
<li><code>-o example.com</code>: the zone origin.</li>
<li><code>-t</code>: print signing statistics.</li>
<li><code>-K</code>: where to find the keys.</li>
</ul>
<p>This creates <code>db.example.com.signed</code> containing:</p>
<ul>
<li>RRSIG records (signatures)</li>
<li>NSEC3 records (authenticated denial of existence)</li>
<li>NSEC3PARAM record</li>
</ul>
<p>Point the zone&rsquo;s <code>file</code> at the <code>.signed</code> file. You have to repeat the signing run before the signatures expire.</p>
<h2 id="automated-dnssec-with-dnssec-policy">Automated DNSSEC with dnssec-policy <a class="anchor" data-pagefind-ignore href="#automated-dnssec-with-dnssec-policy" aria-label="Link to this section">#</a></h2>
<p>BIND 9.16+ supports automatic key management with <code>dnssec-policy</code>. This is the recommended approach: you describe the keys and timings once, and BIND does the rest.</p>
<h3 id="define-dnssec-policies">Define DNSSEC Policies <a class="anchor" data-pagefind-ignore href="#define-dnssec-policies" aria-label="Link to this section">#</a></h3>
<p>A policy says which keys to use, how long they live and how long signatures stay valid. Define it once and reuse it for many zones.</p>
<pre tabindex="0"><code class="language-named" data-lang="named">// /etc/bind/named.conf.options

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

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

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

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

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

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

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

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

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

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

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

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

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

zone &#34;1.168.192.in-addr.arpa&#34; {
    type primary;
    file &#34;/var/cache/bind/zones/db.192.168.1&#34;;
    dnssec-policy &#34;production&#34;;
    inline-signing yes;
    allow-transfer { key &#34;transfer-key&#34;; };
};
</code></pre><ul>
<li><code>allow-transfer { key &quot;transfer-key&quot;; }</code>: only servers with the TSIG key may transfer the zone. They receive the signed version.</li>
<li><code>also-notify</code>: tell the slave server at 192.168.1.2 about changes, including re-signing.</li>
</ul>
<h2 id="troubleshooting-dnssec">Troubleshooting DNSSEC <a class="anchor" data-pagefind-ignore href="#troubleshooting-dnssec" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Cause</th>
					<th>Fix</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Signatures expired</td>
					<td>Re-signing stopped</td>
					<td>Check <code>rndc dnssec -status</code>, force <code>rndc sign</code></td>
			</tr>
			<tr>
					<td>SERVFAIL after DS change</td>
					<td>DS at parent does not match the KSK</td>
					<td>Compare DS records</td>
			</tr>
			<tr>
					<td>Zone not signed</td>
					<td>Key files missing or unreadable</td>
					<td>Check permissions</td>
			</tr>
			<tr>
					<td>Zone won&rsquo;t load</td>
					<td>Syntax error in config or zone</td>
					<td><code>named-checkconf</code>, <code>named-checkzone</code></td>
			</tr>
	</tbody>
</table>
<h3 id="common-issues">Common Issues <a class="anchor" data-pagefind-ignore href="#common-issues" aria-label="Link to this section">#</a></h3>
<p><strong>Signatures expired:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check key and signing state</span>
</span></span><span class="line"><span class="cl">rndc dnssec -status example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Force re-signing</span>
</span></span><span class="line"><span class="cl">rndc sign example.com
</span></span></code></pre></div><p><strong>DS record mismatch:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Compare DS records</span>
</span></span><span class="line"><span class="cl">dig DS example.com @parent-ns
</span></span><span class="line"><span class="cl">dnssec-dsfromkey Kexample.com.+013+12345.key
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Ensure key tag, algorithm, and digest match</span>
</span></span></code></pre></div><p><strong>Key not found:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check key files exist and permissions</span>
</span></span><span class="line"><span class="cl">ls -la /var/cache/bind/keys/
</span></span><span class="line"><span class="cl">chown bind:bind /var/cache/bind/keys/*
</span></span><span class="line"><span class="cl">chmod <span class="m">600</span> /var/cache/bind/keys/*.private
</span></span></code></pre></div><p><strong>Zone won&rsquo;t load:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check configuration</span>
</span></span><span class="line"><span class="cl">named-checkconf
</span></span><span class="line"><span class="cl">named-checkzone example.com /var/cache/bind/zones/db.example.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check logs</span>
</span></span><span class="line"><span class="cl">tail -f /var/log/named/dnssec.log
</span></span></code></pre></div><h2 id="security-best-practices">Security Best Practices <a class="anchor" data-pagefind-ignore href="#security-best-practices" aria-label="Link to this section">#</a></h2>
<ol>
<li><strong>Protect private keys</strong> - Use proper file permissions (600) and consider HSM for high-security deployments</li>
<li><strong>Monitor signature expiry</strong> - Set up alerts for signatures approaching expiry</li>
<li><strong>Test rollovers</strong> - Practice key rollovers in a test environment first</li>
<li><strong>Use NSEC3</strong> - Prevents zone enumeration attacks</li>
<li><strong>Keep BIND updated</strong> - Security fixes often affect DNSSEC</li>
<li><strong>Document procedures</strong> - Especially for manual KSK rollovers</li>
<li><strong>Backup keys securely</strong> - Store encrypted backups offline</li>
</ol>
<h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub: <a href="https://github.com/pderuiter/blog-bind-dnssec-signing" rel="noopener">pderuiter/blog-bind-dnssec-signing</a>. It creates an Ubuntu 24.04 VM on Proxmox and sets up the complete configuration from this post (the <code>production</code> dnssec-policy, inline-signed forward and reverse zones, TSIG-protected transfers and the expiry check script); run <code>terraform apply</code>, then <code>ansible-playbook site.yml</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>DNSSEC on authoritative servers completes the chain of trust for your domains. <code>dnssec-policy</code> with inline signing automates most of the work; monitoring makes sure your zones stay signed.</p>
<p>Key takeaways:</p>
<ul>
<li>Use ECDSAP256SHA256 or ED25519 algorithms</li>
<li>Enable inline-signing for automatic signature maintenance</li>
<li>Use NSEC3 to prevent zone enumeration</li>
<li>Monitor signature expiry proactively</li>
<li>Plan and test key rollovers carefully</li>
</ul>
<p>The next post will cover Response Policy Zones (RPZ), using BIND to block malicious domains and enforce DNS-based security policies.</p>
]]></content:encoded></item><item><title>Enabling DNSSEC Validation on BIND Resolvers</title><link>https://blog.bsdserver.nl/enabling-dnssec-validation-on-bind-resolvers/</link><guid isPermaLink="false">693b6dbb79eb54000160a58e</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:19:55 +0000</pubDate><description>DNSSEC (Domain Name System Security Extensions) adds cryptographic authentication to DNS responses, protecting against cache poisoning and…</description><category>BIND</category><category>DNS</category><category>DNSSEC</category><category>Security</category><category>Linux</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/bind-dnssec-validation.png" medium="image"/><content:encoded><![CDATA[<p>DNSSEC (Domain Name System Security Extensions) adds cryptographic authentication to DNS responses, protecting against cache poisoning and man-in-the-middle attacks. A plain resolver accepts whatever answer arrives first; it cannot tell a forged response from a real one.</p>
<p>This post turns a BIND recursive resolver into a validating resolver. It covers enabling validation, testing it, handling domains with broken DNSSEC, and monitoring the result.</p>
<h2 id="why-dnssec-validation">Why DNSSEC validation? <a class="anchor" data-pagefind-ignore href="#why-dnssec-validation" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Tamper detection</strong>: a forged or modified answer fails signature checks and never reaches the client.</li>
<li><strong>Protects every client</strong>: laptops, servers and IoT devices behind the resolver get validation without any client changes.</li>
<li><strong>Low effort</strong>: modern BIND ships the root trust anchor; one setting turns it on.</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> on every recursive resolver you run. Most signed zones validate fine, and the default in current BIND is already <code>auto</code>.</li>
<li><strong>Skip it</strong> only on a forwarder that sends everything to an upstream resolver you trust to validate, or where the clock cannot be kept accurate (signatures have validity periods).</li>
</ul>
<h2 id="how-dnssec-validation-works">How DNSSEC Validation Works <a class="anchor" data-pagefind-ignore href="#how-dnssec-validation-works" aria-label="Link to this section">#</a></h2>
<p>DNSSEC creates a chain of trust from the DNS root zone down to individual domains:</p>
<table>
	<thead>
			<tr>
					<th>Level</th>
					<th>Signed by</th>
					<th>Role in validation</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Root zone</td>
					<td>ICANN</td>
					<td>Its key is the trust anchor, built into DNS software</td>
			</tr>
			<tr>
					<td>TLD (.com, .org)</td>
					<td>The registry</td>
					<td>Root holds a DS record for the TLD key</td>
			</tr>
			<tr>
					<td>Domain</td>
					<td>The domain owner</td>
					<td>TLD holds a DS record for the domain key</td>
			</tr>
			<tr>
					<td>Resolver</td>
					<td>-</td>
					<td>Checks every signature up to the trust anchor</td>
			</tr>
	</tbody>
</table>
<p>When the resolver receives a signed response, it fetches the zone&rsquo;s DNSKEY records, verifies the RRSIG on the answer, checks the DS record in the parent zone, and repeats up to the root trust anchor.</p>
<p>The flow: client query → resolver fetches answer + RRSIG → DNSKEY → DS in parent → … → root trust anchor → answer with <code>ad</code> flag, or SERVFAIL if any signature fails.</p>
<h2 id="enabling-dnssec-validation-in-bind">Enabling DNSSEC Validation in BIND <a class="anchor" data-pagefind-ignore href="#enabling-dnssec-validation-in-bind" aria-label="Link to this section">#</a></h2>
<p>There are two ways to tell BIND which root key to trust:</p>
<table>
	<thead>
			<tr>
					<th>Option</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>dnssec-validation auto</code></td>
					<td>Almost every resolver. BIND uses its built-in root anchor and keeps it current itself.</td>
			</tr>
			<tr>
					<td><code>dnssec-validation yes</code> + <code>trust-anchors</code></td>
					<td>Explicit control, or setups where you manage anchors yourself. You must update them on a root key rollover.</td>
			</tr>
	</tbody>
</table>
<h3 id="automatic-configuration">Automatic Configuration <a class="anchor" data-pagefind-ignore href="#automatic-configuration" aria-label="Link to this section">#</a></h3>
<p>This is the recommended setup. Add <code>dnssec-validation auto</code> to the <code>options</code> block of a recursive resolver:</p>
<pre tabindex="0"><code>options {
    directory &#34;/var/named&#34;;
    
    recursion yes;
    allow-recursion { trusted; };
    
    dnssec-validation auto;
};
</code></pre><ul>
<li><code>dnssec-validation auto</code>: use the built-in managed trust anchors for the root zone. BIND keeps them up to date through RFC 5011 automated trust anchor maintenance.</li>
<li><code>allow-recursion { trusted; }</code>: only your own networks may use the resolver (the <code>trusted</code> ACL is defined in the complete configuration below).</li>
</ul>
<h3 id="manual-trust-anchor-configuration">Manual Trust Anchor Configuration <a class="anchor" data-pagefind-ignore href="#manual-trust-anchor-configuration" aria-label="Link to this section">#</a></h3>
<p>Use this only if you need explicit control. Include both root KSKs: the root zone rolled from KSK-2017 (key tag 20326) to KSK-2024 (key tag 38696) in October 2026, and the root DNSKEY set is now signed by 38696. A fresh resolver that only knows 20326 returns SERVFAIL for every signed name.</p>
<pre tabindex="0"><code>trust-anchors {
    // KSK-2017 (20326), still published in the root zone during the rollover
    . initial-key 257 3 8 &#34;AwEAAaz/tAm8yTn4Mfeh5eyI96WSVexTBAvkMgJzkKTOiW1vkIbzxeF3
        +/4RgWOq7HrxRixHlFlExOLAJr5emLvN7SWXgnLh4+B5xQlNVz8Og8kv
        ArMtNROxVQuCaSnIDdD5LKyWbRd2n9WGe2R8PzgCmr3EgVLrjyBxWezF
        0jLHwVN8efS3rCj/EWgvIWgb9tarpVUDK/b58Da+sqqls3eNbuv7pr+e
        oZG+SrDK6nWeL3c6H5Apxz7LjVc1uTIdsIXxuOLYA4/ilBmSVIzuDWfd
        RUfhHdY6+cn8HFRm+2hM8AnXGXws9555KrUB5qihylGa8subX2Nn6UwN
        R1AkUTV74bU=&#34;;
    // KSK-2024 (38696), the key that signs the root DNSKEY set
    . initial-ds 38696 8 2 &#34;683D2D0ACB8C9B712A1948B27F741219298D0A450D612C483AF444A4C0FB2B16&#34;;
};

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

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

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

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

zone &#34;.&#34; {
    type hint;
    file &#34;named.ca&#34;;
};
</code></pre><p>What the settings outside DNSSEC do:</p>
<ul>
<li><code>acl &quot;trusted&quot;</code>: the networks allowed to use the resolver; used by <code>allow-recursion</code> and <code>allow-query-cache</code>.</li>
<li><code>version &quot;not disclosed&quot;</code>: hide the BIND version from <code>version.bind</code> queries.</li>
<li><code>minimal-responses yes</code>: leave optional records out of answers; smaller responses.</li>
<li><code>prefetch 10 60</code>: refresh popular records shortly before they expire, so clients do not wait for a cache miss.</li>
<li><code>severity debug</code> on <code>dnssec_log</code>: more detail than the earlier example; lower it to <code>info</code> once things work.</li>
</ul>
<h2 id="testing-dnssec-validation">Testing DNSSEC Validation <a class="anchor" data-pagefind-ignore href="#testing-dnssec-validation" aria-label="Link to this section">#</a></h2>
<h3 id="command-line-tests">Command Line Tests <a class="anchor" data-pagefind-ignore href="#command-line-tests" aria-label="Link to this section">#</a></h3>
<p>Run these after every config change. Signed domains should show <code>ad</code>, broken ones SERVFAIL, unsigned ones resolve without <code>ad</code>.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check if validation is enabled</span>
</span></span><span class="line"><span class="cl">dig @localhost . SOA +dnssec <span class="p">|</span> grep -E <span class="s2">&#34;(flags|ad)&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test known-good signed domain</span>
</span></span><span class="line"><span class="cl">dig @localhost cloudflare.com +dnssec +short
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test validation failure (should return SERVFAIL)</span>
</span></span><span class="line"><span class="cl">dig @localhost dnssec-failed.org
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check AD flag on signed domain</span>
</span></span><span class="line"><span class="cl">dig @localhost sigok.verteiltesysteme.net <span class="p">|</span> grep <span class="s2">&#34;flags:&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check that AD flag is absent for unsigned domain (no &#34;ad&#34; in the flags line)</span>
</span></span><span class="line"><span class="cl">dig @localhost unsigned-domain.com <span class="p">|</span> grep <span class="s2">&#34;flags:&#34;</span>
</span></span></code></pre></div><h3 id="using-drill-from-ldns">Using drill (from ldns) <a class="anchor" data-pagefind-ignore href="#using-drill-from-ldns" aria-label="Link to this section">#</a></h3>
<p><code>drill</code> traces the chain from the root and shows each signature it checks, a useful second opinion next to <code>delv</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Trace DNSSEC chain</span>
</span></span><span class="line"><span class="cl">drill -DT cloudflare.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Show signature details</span>
</span></span><span class="line"><span class="cl">drill -TD cloudflare.com
</span></span></code></pre></div><h2 id="monitoring-dnssec-health">Monitoring DNSSEC Health <a class="anchor" data-pagefind-ignore href="#monitoring-dnssec-health" aria-label="Link to this section">#</a></h2>
<h3 id="statistics">Statistics <a class="anchor" data-pagefind-ignore href="#statistics" aria-label="Link to this section">#</a></h3>
<p>BIND counts validation results. <code>rndc stats</code> writes them to the statistics file:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># View DNSSEC statistics (written to statistics-file, default &#34;named.stats&#34; in the working directory)</span>
</span></span><span class="line"><span class="cl">rndc stats
</span></span><span class="line"><span class="cl">grep <span class="s2">&#34;DNSSEC&#34;</span> /var/named/named.stats
</span></span></code></pre></div><p>The text dump labels these counters &ldquo;DNSSEC validation attempted/succeeded/failed&rdquo;. In the XML/JSON statistics channel they are called:</p>
<ul>
<li><code>ValOk</code>: Successful validations</li>
<li><code>ValNegOk</code>: Validated negative responses</li>
<li><code>ValFail</code>: Validation failures</li>
<li><code>ValIndeterminate</code>: Non-DNSSEC responses</li>
</ul>
<h3 id="alerting-on-failures">Alerting on Failures <a class="anchor" data-pagefind-ignore href="#alerting-on-failures" aria-label="Link to this section">#</a></h3>
<p>This check queries a signed domain and fails if the <code>ad</code> flag is missing. It fits Nagios-style monitoring (exit 2 = critical).</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># /usr/local/bin/check-dnssec.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">RESULT</span><span class="o">=</span><span class="k">$(</span>dig @localhost cloudflare.com +dnssec +short 2&gt;<span class="p">&amp;</span>1<span class="k">)</span>
</span></span><span class="line"><span class="cl"><span class="nv">AD_FLAG</span><span class="o">=</span><span class="k">$(</span>dig @localhost cloudflare.com <span class="p">|</span> grep -cE <span class="s2">&#34;flags:.* ad[ ;]&#34;</span><span class="k">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">if</span> <span class="o">[</span> <span class="nv">$AD_FLAG</span> -eq <span class="m">0</span> <span class="o">]</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">    <span class="nb">echo</span> <span class="s2">&#34;CRITICAL: DNSSEC validation not working&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="nb">exit</span> <span class="m">2</span>
</span></span><span class="line"><span class="cl"><span class="k">fi</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;OK: DNSSEC validation operational&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nb">exit</span> <span class="m">0</span>
</span></span></code></pre></div><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Likely cause</th>
					<th>Check</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>SERVFAIL for one signed domain</td>
					<td>Broken DNSSEC on that domain, or authoritative servers unreachable</td>
					<td><code>+cd</code> query, <code>delv</code>, <code>dnssec.log</code></td>
			</tr>
			<tr>
					<td>SERVFAIL for every signed domain</td>
					<td>Clock wrong, or stale trust anchor</td>
					<td><code>date</code>, <code>rndc managed-keys status</code></td>
			</tr>
			<tr>
					<td>No <code>ad</code> flag anywhere</td>
					<td>Validation off</td>
					<td><code>dnssec-validation</code> setting</td>
			</tr>
	</tbody>
</table>
<h3 id="servfail-for-dnssec-domains">&ldquo;SERVFAIL&rdquo; for DNSSEC Domains <a class="anchor" data-pagefind-ignore href="#servfail-for-dnssec-domains" aria-label="Link to this section">#</a></h3>
<p>First check that the resolver can reach the authoritative servers, then repeat the query with validation disabled:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Try direct query to authoritative</span>
</span></span><span class="line"><span class="cl">dig @ns1.example.com example.com DNSKEY
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check if DNSKEY is retrievable</span>
</span></span><span class="line"><span class="cl">dig @localhost example.com DNSKEY +cd
</span></span></code></pre></div><p>The <code>+cd</code> flag (Checking Disabled) bypasses validation - if this works but normal query fails, the issue is DNSSEC.</p>
<h3 id="clock-skew">Clock Skew <a class="anchor" data-pagefind-ignore href="#clock-skew" aria-label="Link to this section">#</a></h3>
<p>DNSSEC signatures have validity periods. A wrong system clock makes valid signatures look expired or not yet valid:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check time</span>
</span></span><span class="line"><span class="cl">date
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Sync time (chrony)</span>
</span></span><span class="line"><span class="cl">chronyc makestep
</span></span><span class="line"><span class="cl"><span class="c1"># or</span>
</span></span><span class="line"><span class="cl">timedatectl set-ntp <span class="nb">true</span>
</span></span></code></pre></div><h3 id="trust-anchor-problems">Trust Anchor Problems <a class="anchor" data-pagefind-ignore href="#trust-anchor-problems" aria-label="Link to this section">#</a></h3>
<p>If the managed keys are missing or stale, every signed domain fails. Check the managed keys state and file:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Check managed keys</span>
</span></span><span class="line"><span class="cl">rndc managed-keys status
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Verify root key file exists</span>
</span></span><span class="line"><span class="cl">ls -la /var/named/managed-keys.bind
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check key validity (the file stores KEYDATA records with key id and &#34;trusted since&#34;)</span>
</span></span><span class="line"><span class="cl">grep -A12 <span class="s2">&#34;KEYDATA&#34;</span> /var/named/managed-keys.bind
</span></span></code></pre></div><h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub: <a href="https://github.com/pderuiter/blog-bind-dnssec-validation" rel="noopener">pderuiter/blog-bind-dnssec-validation</a>. Terraform creates an Ubuntu 24.04 VM on Proxmox, and <code>ansible-playbook site.yml</code> turns it into the validating resolver from this post, including the logging channels and the <code>check-dnssec.sh</code> script; <code>tests/verify.yml</code> runs the checks above.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>DNSSEC validation on your resolver protects all clients from DNS spoofing attacks. Turn it on with <code>dnssec-validation auto</code>, log the <code>dnssec</code> category, watch the validation counters, and use Negative Trust Anchors only for domains whose DNSSEC is broken.</p>
<p>The next post will cover signing your own zones with DNSSEC on authoritative servers, completing the DNSSEC trust chain for your domains.</p>
]]></content:encoded></item><item><title>Implementing DNS-Based Security with BIND Response Policy Zones</title><link>https://blog.bsdserver.nl/implementing-dns-based-security-with-bind-response-policy-zones/</link><guid isPermaLink="false">693b6d5379eb54000160a580</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:18:11 +0000</pubDate><description>Response Policy Zones (RPZ) provide DNS-level security by allowing you to override DNS responses for specific domains.</description><category>BIND</category><category>DNS</category><category>Response Policy Zones</category><category>Security</category><category>Malware</category><category>Linux</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/bind-rpz.png" medium="image"/><content:encoded><![CDATA[<p>Response Policy Zones (RPZ) provide DNS-level security by allowing you to override DNS responses for specific domains. Malware, phishing and tracking all start with a DNS lookup; if the lookup fails, the connection never happens.</p>
<p>This post sets up RPZ on a BIND recursive resolver. It covers the policy actions and triggers, external blocklists with automatic updates, a block page, whitelisting and logging.</p>
<h2 id="why-rpz">Why RPZ? <a class="anchor" data-pagefind-ignore href="#why-rpz" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>One control point</strong>: every device using the resolver is protected, including IoT devices and guests you cannot install software on.</li>
<li><strong>Blocks before the connection</strong>: the client never gets an address for a blocked domain.</li>
<li><strong>Standard format</strong>: blocklists are ordinary DNS zones; they can be transferred between servers like any zone.</li>
<li><strong>Visibility</strong>: RPZ logs show which client looked up which blocked domain.</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> on resolvers you control, to block known-bad domains, ads or trackers network-wide.</li>
<li><strong>Skip it</strong> on authoritative-only servers: RPZ only applies to recursive queries. It also cannot help clients that bypass your resolver (hard-coded DNS servers, DNS over HTTPS).</li>
</ul>
<h2 id="how-rpz-works">How RPZ Works <a class="anchor" data-pagefind-ignore href="#how-rpz-works" aria-label="Link to this section">#</a></h2>
<p>RPZ is a zone loaded by the resolver. Each record in it is a rule: the owner name says what to match (the trigger), the record data says what to answer instead (the action).</p>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>BIND resolver</td>
					<td>Your DNS server</td>
					<td>Resolves queries and applies the policy zones</td>
			</tr>
			<tr>
					<td>RPZ zones</td>
					<td>Same server (local file or transferred)</td>
					<td>Hold the rules</td>
			</tr>
			<tr>
					<td>Update script</td>
					<td>Same server (cron)</td>
					<td>Converts external blocklists into an RPZ zone</td>
			</tr>
			<tr>
					<td>Block page (optional)</td>
					<td>A web server</td>
					<td>Explains to users why a site is blocked</td>
			</tr>
	</tbody>
</table>
<p>The flow: client query → BIND checks the RPZ zones → match: rewritten answer and a log line → no match: normal resolution.</p>
<p>The rewritten answer can be:</p>
<table>
	<thead>
			<tr>
					<th>Action</th>
					<th>Client sees</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>NXDOMAIN</td>
					<td>Domain doesn&rsquo;t exist</td>
			</tr>
			<tr>
					<td>NODATA</td>
					<td>Domain exists but has no records of the requested type</td>
			</tr>
			<tr>
					<td>Custom IP</td>
					<td>An address of your choice: walled garden or block page</td>
			</tr>
			<tr>
					<td>CNAME</td>
					<td>Redirect to another domain</td>
			</tr>
			<tr>
					<td>Passthru</td>
					<td>The real answer (overrides more general rules)</td>
			</tr>
			<tr>
					<td>Drop</td>
					<td>No response at all</td>
			</tr>
	</tbody>
</table>
<h2 id="enabling-rpz-in-bind">Enabling RPZ in BIND <a class="anchor" data-pagefind-ignore href="#enabling-rpz-in-bind" aria-label="Link to this section">#</a></h2>
<h3 id="basic-configuration">Basic Configuration <a class="anchor" data-pagefind-ignore href="#basic-configuration" aria-label="Link to this section">#</a></h3>
<p>Two parts: the <code>response-policy</code> statement in <code>options</code> lists the policy zones, and each policy zone is a normal zone definition.</p>
<pre tabindex="0"><code>options {
    directory &#34;/var/named&#34;;
    recursion yes;
    allow-recursion { trusted; };
    
    response-policy {
        zone &#34;rpz.local&#34;;
    } qname-wait-recurse no;
};

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

    IN  NS  localhost.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    IN  NS  localhost.

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

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

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

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

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

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

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

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

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

zone &#34;.&#34; {
    type hint;
    file &#34;named.ca&#34;;
};
</code></pre><ul>
<li><code>policy passthru</code> on <code>rpz-whitelist</code>: every name in that zone resolves normally, whatever its record says.</li>
<li><code>policy given</code> on the blocklists: use the action from each record.</li>
</ul>
<h2 id="testing-rpz">Testing RPZ <a class="anchor" data-pagefind-ignore href="#testing-rpz" aria-label="Link to this section">#</a></h2>
<h3 id="verify-blocking">Verify Blocking <a class="anchor" data-pagefind-ignore href="#verify-blocking" aria-label="Link to this section">#</a></h3>
<p>Query a domain from your blocklist and check the log:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Query blocked domain</span>
</span></span><span class="line"><span class="cl">dig @localhost blocked-domain.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Should return NXDOMAIN or your block page IP</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check RPZ logs</span>
</span></span><span class="line"><span class="cl">tail -f /var/log/named/rpz.log
</span></span></code></pre></div><h3 id="test-passthru">Test Passthru <a class="anchor" data-pagefind-ignore href="#test-passthru" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Verify whitelisted domain resolves normally</span>
</span></span><span class="line"><span class="cl">dig @localhost whitelisted-domain.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Should return actual IP, not blocked</span>
</span></span></code></pre></div><h3 id="debug-mode">Debug Mode <a class="anchor" data-pagefind-ignore href="#debug-mode" aria-label="Link to this section">#</a></h3>
<p>If a rule does not fire, turn on query logging temporarily to see what clients actually ask:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">rndc querylog on
</span></span><span class="line"><span class="cl"><span class="c1"># Run tests</span>
</span></span><span class="line"><span class="cl">rndc querylog off
</span></span></code></pre></div><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Likely cause</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Blocked domain still resolves</td>
					<td>Zone not listed in <code>response-policy</code>, missing <code>*.</code> rule for subdomains, or update not yet applied (<code>min-update-interval</code>)</td>
			</tr>
			<tr>
					<td>SERVFAIL instead of block answer</td>
					<td><code>qname-wait-recurse</code> left at <code>yes</code> and the domain&rsquo;s name servers are broken</td>
			</tr>
			<tr>
					<td>Whitelisted domain still blocked</td>
					<td>Whitelist zone is not listed first</td>
			</tr>
			<tr>
					<td>No effect at all</td>
					<td>Client uses another resolver, or the server is authoritative-only</td>
			</tr>
	</tbody>
</table>
<h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub: <a href="https://github.com/pderuiter/blog-bind-rpz" rel="noopener">pderuiter/blog-bind-rpz</a>. It creates an Ubuntu 24.04 VM on Proxmox and builds the resolver from this post with the whitelist, local and blocklist RPZ zones, the conversion and daily update scripts and RPZ logging (the block page is optional); run <code>terraform apply</code>, then <code>ansible-playbook site.yml</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>Response Policy Zones provide DNS-level security without client software or network proxies. Combine regularly updated blocklists, a local whitelist and logging for an effective first line of defense against malware, phishing and unwanted content.</p>
<p>The next post will cover DNS over TLS (DoT), adding transport encryption to your DNS infrastructure for privacy and security.</p>
]]></content:encoded></item><item><title>BIND Zone Security: Views, ACLs, and Query Restrictions</title><link>https://blog.bsdserver.nl/bind-zone-security-views-acls-and-query-restrictions/</link><guid isPermaLink="false">693b6bf979eb54000160a55c</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:12:25 +0000</pubDate><description>A properly secured DNS server is critical infrastructure.</description><category>BIND</category><category>DNS</category><category>Security</category><category>ACLs</category><category>Linux</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/bind-zone-security.png" medium="image"/><content:encoded><![CDATA[<p>A properly secured DNS server is critical infrastructure. An open resolver can be abused for DNS amplification attacks, leak internal network information, or serve as a reconnaissance tool for attackers.</p>
<p>This guide covers BIND&rsquo;s security features: Access Control Lists (ACLs), query and transfer restrictions, views for split-horizon DNS, rate limiting and security logging. It ends with one complete configuration that combines them.</p>
<h2 id="understanding-the-threat-model">Understanding the Threat Model <a class="anchor" data-pagefind-ignore href="#understanding-the-threat-model" aria-label="Link to this section">#</a></h2>
<p>Each threat has a matching BIND feature:</p>
<table>
	<thead>
			<tr>
					<th>Threat</th>
					<th>What happens</th>
					<th>Defence in this post</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Open resolver abuse</td>
					<td>Attackers use your server to amplify DDoS attacks</td>
					<td><code>allow-recursion</code>, rate limiting</td>
			</tr>
			<tr>
					<td>Information disclosure</td>
					<td>Internal hostnames and IPs leak to the internet</td>
					<td>Views, per-zone <code>allow-query</code></td>
			</tr>
			<tr>
					<td>Cache poisoning</td>
					<td>Malicious records injected into resolver caches</td>
					<td>Restricted recursion, DNSSEC validation</td>
			</tr>
			<tr>
					<td>Zone transfer exposure</td>
					<td>Unauthorized parties download your entire zone</td>
					<td><code>allow-transfer</code>, TSIG</td>
			</tr>
			<tr>
					<td>Resource exhaustion</td>
					<td>Query floods consume server resources</td>
					<td>Rate limiting, minimal responses</td>
			</tr>
	</tbody>
</table>
<h3 id="when-to-use-what">When to use what <a class="anchor" data-pagefind-ignore href="#when-to-use-what" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Every server</strong>: ACLs, restricted transfers, hidden version, rate limiting.</li>
<li><strong>Resolvers</strong>: restrict recursion and cache access to your own networks.</li>
<li><strong>Views</strong>: only when internal and external clients must get different answers for the same zone.</li>
</ul>
<h2 id="access-control-lists-acls">Access Control Lists (ACLs) <a class="anchor" data-pagefind-ignore href="#access-control-lists-acls" aria-label="Link to this section">#</a></h2>
<p>ACLs define groups of IP addresses that can be referenced throughout your configuration. Define them once, use them everywhere: changing a network then means editing one list.</p>
<h3 id="basic-acl-syntax">Basic ACL Syntax <a class="anchor" data-pagefind-ignore href="#basic-acl-syntax" aria-label="Link to this section">#</a></h3>
<p>Name each ACL after the role of the clients, so the options that use it read clearly (<code>allow-transfer { secondary-servers; }</code>).</p>
<pre tabindex="0"><code>acl &#34;trusted&#34; {
    localhost;
    localnets;
    192.168.0.0/16;
    10.0.0.0/8;
};

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

logging {
    channel default_log {
        file &#34;/var/log/named/named.log&#34; versions 5 size 10m;
        severity info;
        print-time yes;
        print-severity yes;
    };
    
    channel security_log {
        file &#34;/var/log/named/security.log&#34; versions 5 size 10m;
        severity info;
        print-time yes;
    };
    
    category default { default_log; };
    category security { security_log; };
    category xfer-in { security_log; };
    category xfer-out { security_log; };
};
</code></pre><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Likely cause</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Internal clients get external answers</td>
					<td>Client IP not in the internal view&rsquo;s <code>match-clients</code>, or the views are in the wrong order</td>
			</tr>
			<tr>
					<td><code>named-checkconf</code>: zone not in a view</td>
					<td>With views, every zone (also from <code>named.conf.local</code>) must be inside a view</td>
			</tr>
			<tr>
					<td>Internal clients get <code>REFUSED</code> for internet names</td>
					<td>Recursion off or root hint zone missing in their view</td>
			</tr>
			<tr>
					<td>Slave transfer refused</td>
					<td>Slave IP or TSIG key missing from <code>allow-transfer</code>; check the security log</td>
			</tr>
	</tbody>
</table>
<h2 id="security-checklist">Security Checklist <a class="anchor" data-pagefind-ignore href="#security-checklist" aria-label="Link to this section">#</a></h2>
<p>Before putting your BIND server into production:</p>
<ol>
<li><strong>Recursion</strong>: Disabled or restricted to trusted networks only</li>
<li><strong>Zone transfers</strong>: Restricted to secondary servers, preferably with TSIG</li>
<li><strong>Version string</strong>: Hidden to prevent fingerprinting</li>
<li><strong>Rate limiting</strong>: Enabled to prevent amplification abuse</li>
<li><strong>ACLs</strong>: Defined and applied consistently</li>
<li><strong>Views</strong>: Configured if split-horizon is needed</li>
<li><strong>Logging</strong>: Security events logged for auditing</li>
<li><strong>DNSSEC</strong>: Validation enabled for resolvers</li>
<li><strong>Updates</strong>: Disabled or restricted with TSIG keys</li>
<li><strong>Firewall</strong>: Port 53 restricted appropriately</li>
</ol>
<h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub:
<a href="https://github.com/pderuiter/blog-bind-views-acls" rel="noopener">pderuiter/blog-bind-views-acls</a>. It creates an Ubuntu 24.04 VM on Proxmox and applies the complete secure configuration from this post, with the ACLs, the internal and external views, TSIG-only transfers, rate limiting and security logging; put the transfer key in an ansible-vault file, then run <code>terraform apply</code> and <code>ansible-playbook site.yml</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>DNS security requires defense in depth. ACLs provide the foundation, views enable split-horizon deployments, and query restrictions prevent abuse. Rate limiting, minimal responses and logging complete the picture.</p>
<p>The next post will cover dynamic DNS updates with TSIG authentication, allowing secure automated record management.</p>
]]></content:encoded></item><item><title>How to Configure BIND RNDC and TSIG Keys for Remote DNS Management</title><link>https://blog.bsdserver.nl/how-to-configure-bind-rndc-and-tsig-keys-for-remote-dns-management/</link><guid isPermaLink="false">693b6bae79eb54000160a54e</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:11:10 +0000</pubDate><description>RNDC (Remote Name Daemon Control) is the administrative tool for managing BIND DNS servers.</description><category>BIND</category><category>DNS</category><category>rndc</category><category>TSIG</category><category>Security</category><category>Linux</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/bind-rndc-tsig.png" medium="image"/><content:encoded><![CDATA[<p>RNDC (Remote Name Daemon Control) is the administrative tool for managing BIND DNS servers. It reloads zones, flushes caches and shows statistics without restarting the service.</p>
<p>This post sets up RNDC keys for local and remote administration, a read-only channel for monitoring, and TSIG keys that authenticate zone transfers between master and slave.</p>
<h2 id="why-rndc-and-tsig">Why RNDC and TSIG? <a class="anchor" data-pagefind-ignore href="#why-rndc-and-tsig" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>No restarts</strong>: reload a zone or the configuration while <code>named</code> keeps answering.</li>
<li><strong>Remote control</strong>: manage several DNS servers from one admin workstation.</li>
<li><strong>Authenticated</strong>: every command and every zone transfer is signed with a shared secret.</li>
<li><strong>Least privilege</strong>: separate keys and read-only channels for monitoring.</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> on every BIND server: local RNDC is the normal way to reload zones. Add remote access and TSIG when you run more than one server.</li>
<li><strong>Skip</strong> remote RNDC if you manage servers only over SSH; keep the local channel.</li>
</ul>
<h2 id="how-it-works">How It Works <a class="anchor" data-pagefind-ignore href="#how-it-works" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Piece</th>
					<th>Protects</th>
					<th>Where</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>RNDC key + <code>controls</code></td>
					<td>Admin commands to <code>named</code></td>
					<td>TCP port 953 (by default)</td>
			</tr>
			<tr>
					<td><code>rndc.conf</code></td>
					<td>Which key and server the <code>rndc</code> client uses</td>
					<td>Admin workstation or the server itself</td>
			</tr>
			<tr>
					<td>TSIG transfer key</td>
					<td>Zone transfers and NOTIFY between master and slave</td>
					<td>Port 53, inside the DNS messages</td>
			</tr>
	</tbody>
</table>
<p>Both use the same mechanism: a shared HMAC secret. <strong>RNDC</strong> signs each command with it; <strong>TSIG</strong> (Transaction Signature) signs DNS messages with it. A message without a valid signature is rejected.</p>
<p>The flow for a remote reload: <code>rndc -s dns1 reload</code> → the client signs the command with the key from <code>rndc.conf</code> → <code>named</code> checks the source IP against <code>allow</code> and the signature against <code>keys</code> → runs the command.</p>
<h2 id="generating-rndc-keys">Generating RNDC Keys <a class="anchor" data-pagefind-ignore href="#generating-rndc-keys" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Command</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>rndc-confgen -a</code></td>
					<td>Local administration only; writes a key file <code>named</code> reads automatically</td>
			</tr>
			<tr>
					<td><code>rndc-confgen</code></td>
					<td>Remote administration; prints a full <code>rndc.conf</code> and the matching <code>named.conf</code> snippet</td>
			</tr>
			<tr>
					<td><code>tsig-keygen</code></td>
					<td>Zone transfer and dynamic update keys (see below)</td>
			</tr>
	</tbody>
</table>
<h3 id="automatic-generation">Automatic Generation <a class="anchor" data-pagefind-ignore href="#automatic-generation" aria-label="Link to this section">#</a></h3>
<p>The simplest way to set up RNDC is using <code>rndc-confgen</code> with the <code>-a</code> flag:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">rndc-confgen -a
</span></span></code></pre></div><p>This creates <code>/etc/rndc.key</code> (RHEL) or <code>/etc/bind/rndc.key</code> (Debian/Ubuntu) with a randomly generated key:</p>
<pre tabindex="0"><code>key &#34;rndc-key&#34; {
    algorithm hmac-sha256;
    secret &#34;base64-encoded-secret&#34;;
};
</code></pre><p>BIND automatically includes this file, so no additional configuration is needed for local administration. However, <code>rndc-confgen -a</code> creates the file mode <code>0600</code> and owned by root, so <code>named</code>, which runs as <code>named</code> (RHEL) or <code>bind</code> (Debian/Ubuntu), cannot read it. The log then shows <code>open: /etc/rndc.key: permission denied</code> and <code>rndc</code> fails with <code>connection to remote host closed</code>. Either pass the daemon user with <code>-u</code>, or fix ownership afterwards and restart <code>named</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">rndc-confgen -a -u named          <span class="c1"># Debian/Ubuntu: -u bind</span>
</span></span><span class="line"><span class="cl"><span class="c1"># or</span>
</span></span><span class="line"><span class="cl">chown root:named /etc/rndc.key <span class="o">&amp;&amp;</span> chmod <span class="m">640</span> /etc/rndc.key
</span></span></code></pre></div><h3 id="manual-generation">Manual Generation <a class="anchor" data-pagefind-ignore href="#manual-generation" aria-label="Link to this section">#</a></h3>
<p>For remote administration you need the key on both sides. Without <code>-a</code>, <code>rndc-confgen</code> prints both halves:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">rndc-confgen
</span></span></code></pre></div><p>This outputs both the <code>rndc.conf</code> content and the corresponding <code>named.conf</code> additions:</p>
<pre tabindex="0"><code># Start of rndc.conf
key &#34;rndc-key&#34; {
    algorithm hmac-sha256;
    secret &#34;wImDGsj5MxtGQl1nL0V2V/eTlpKs3VdS4nKxEhJVyKY=&#34;;
};

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# Update key - dynamic updates only
key &#34;update-key&#34; {
    algorithm hmac-sha256;
    secret &#34;update-secret&#34;;
};
</code></pre><h3 id="firewall-rules">Firewall Rules <a class="anchor" data-pagefind-ignore href="#firewall-rules" aria-label="Link to this section">#</a></h3>
<p>Restrict the RNDC port to the admin network, as a second layer behind <code>allow</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Allow RNDC only from admin network</span>
</span></span><span class="line"><span class="cl">iptables -A INPUT -p tcp --dport <span class="m">953</span> -s 192.168.1.0/24 -j ACCEPT
</span></span><span class="line"><span class="cl">iptables -A INPUT -p tcp --dport <span class="m">953</span> -j DROP
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Or with firewalld</span>
</span></span><span class="line"><span class="cl">firewall-cmd --permanent --add-rich-rule<span class="o">=</span><span class="s1">&#39;rule family=ipv4 source address=192.168.1.0/24 port port=953 protocol=tcp accept&#39;</span>
</span></span></code></pre></div><h3 id="avoid-storing-keys-in-main-config">Avoid Storing Keys in Main Config <a class="anchor" data-pagefind-ignore href="#avoid-storing-keys-in-main-config" aria-label="Link to this section">#</a></h3>
<p>Keep secrets in separate files and include them, so you can share <code>named.conf</code> without leaking keys:</p>
<pre tabindex="0"><code>include &#34;/etc/named/keys/rndc.key&#34;;
include &#34;/etc/named/keys/transfer.key&#34;;
</code></pre><p>This keeps sensitive data separate and simplifies key rotation.</p>
<h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Likely cause</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>connection refused</code></td>
					<td><code>named</code> not running, or no <code>controls</code> channel on that address/port</td>
			</tr>
			<tr>
					<td><code>connection to remote host closed</code></td>
					<td>Wrong key, wrong source IP, or <code>named</code> cannot read <code>rndc.key</code></td>
			</tr>
			<tr>
					<td><code>decode base64 secret</code></td>
					<td>Secret in <code>rndc.conf</code> is not valid base64</td>
			</tr>
			<tr>
					<td>Permission errors</td>
					<td>File ownership, SELinux or AppArmor</td>
			</tr>
	</tbody>
</table>
<h3 id="connection-refused">Connection Refused <a class="anchor" data-pagefind-ignore href="#connection-refused" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">rndc status
</span></span><span class="line"><span class="cl"><span class="c1"># rndc: connect failed: 127.0.0.1#953: connection refused</span>
</span></span></code></pre></div><p>Check that <code>named</code> is running and the controls statement is configured:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">systemctl status named
</span></span><span class="line"><span class="cl">named-checkconf /etc/named.conf
</span></span><span class="line"><span class="cl">ss -tlnp <span class="p">|</span> grep <span class="m">953</span>
</span></span></code></pre></div><h3 id="authentication-failure">Authentication Failure <a class="anchor" data-pagefind-ignore href="#authentication-failure" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">rndc status
</span></span><span class="line"><span class="cl"><span class="c1"># rndc: connection to remote host closed.</span>
</span></span><span class="line"><span class="cl"><span class="c1"># * This may indicate that the</span>
</span></span><span class="line"><span class="cl"><span class="c1"># * remote server is using an older</span>
</span></span><span class="line"><span class="cl"><span class="c1"># * version of the command protocol,</span>
</span></span><span class="line"><span class="cl"><span class="c1"># * this host is not authorized to connect,</span>
</span></span><span class="line"><span class="cl"><span class="c1"># * the clocks are not synchronized,</span>
</span></span><span class="line"><span class="cl"><span class="c1"># * the key signing algorithm is incorrect</span>
</span></span><span class="line"><span class="cl"><span class="c1"># * or the key is invalid.</span>
</span></span></code></pre></div><p>On the server, <code>named</code> logs <code>invalid command from 127.0.0.1#...: bad auth</code>. A secret that is not valid base64 fails earlier, on the client: <code>rndc: decode base64 secret: bad base64 encoding</code>.</p>
<p>Verify keys match between <code>rndc.conf</code> and the key <code>named</code> uses (<code>named.conf</code>, or <code>rndc.key</code> when there is no <code>controls</code> statement):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Compare secrets</span>
</span></span><span class="line"><span class="cl">grep secret /etc/rndc.conf
</span></span><span class="line"><span class="cl">grep -A2 <span class="s1">&#39;key &#34;rndc-key&#34;&#39;</span> /etc/named.conf
</span></span><span class="line"><span class="cl">grep secret /etc/rndc.key
</span></span></code></pre></div><h3 id="permission-denied">Permission Denied <a class="anchor" data-pagefind-ignore href="#permission-denied" aria-label="Link to this section">#</a></h3>
<p>Check file permissions and SELinux:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">ls -la /etc/rndc.key
</span></span><span class="line"><span class="cl">getenforce
</span></span><span class="line"><span class="cl">ausearch -m AVC -ts recent <span class="p">|</span> grep named
</span></span></code></pre></div><h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub:
<a href="https://github.com/pderuiter/blog-bind-rndc-tsig" rel="noopener">pderuiter/blog-bind-rndc-tsig</a>. It creates a master, a slave and an admin workstation, sets up the admin and read-only monitoring control channels, the TSIG-signed zone transfer and the workstation&rsquo;s <code>rndc.conf</code>; put your keys in an ansible-vault file, then run <code>terraform apply</code> and <code>ansible-playbook site.yml</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>RNDC and TSIG keys make DNS administration safe to do remotely. Use HMAC-SHA256 or HMAC-SHA512, separate keys per purpose, a read-only channel for monitoring, and restrict network access to the RNDC port.</p>
<p>The next post in this series will cover zone security, including views, ACLs, and query restrictions to protect your DNS infrastructure from abuse.</p>
]]></content:encoded></item><item><title>How to Setup BIND as a Recursive DNS Resolver</title><link>https://blog.bsdserver.nl/how-to-setup-bind-as-a-recursive-dns-resolver/</link><guid isPermaLink="false">693b6a5f79eb54000160a535</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:05:35 +0000</pubDate><description>A recursive DNS resolver is the workhorse of DNS infrastructure, handling client queries by recursively querying authoritative nameservers until it finds…</description><category>Linux</category><category>DNS</category><category>BIND</category><category>Networking</category><category>Security</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/bind-recursive-resolver.png" medium="image"/><content:encoded><![CDATA[<p>A recursive DNS resolver is the workhorse of DNS infrastructure, handling client queries by recursively querying authoritative nameservers until it finds the answer. BIND 9 is the most widely deployed DNS software and makes an excellent choice for running your own resolver.</p>
<p>This guide sets up a BIND resolver that only serves your own networks, validates DNSSEC, resists abuse, and logs what matters.</p>
<h2 id="why-run-your-own-resolver">Why Run Your Own Resolver? <a class="anchor" data-pagefind-ignore href="#why-run-your-own-resolver" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Privacy</strong>: your DNS queries stay on your network instead of going to third-party providers.</li>
<li><strong>Performance</strong>: local caching reduces latency for repeated queries.</li>
<li><strong>Control</strong>: you can implement custom filtering, logging, and policies.</li>
<li><strong>Reliability</strong>: no dependency on external DNS providers.</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> for an office, lab or data centre network where you want caching, logging or filtering under your own control.</li>
<li><strong>Skip it</strong> for a single machine or a small home network where your router or a public resolver is good enough.</li>
</ul>
<h2 id="how-it-works">How It Works <a class="anchor" data-pagefind-ignore href="#how-it-works" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Clients</td>
					<td>Your trusted networks</td>
					<td>Send every lookup to the resolver</td>
			</tr>
			<tr>
					<td>BIND resolver</td>
					<td>One server (or two for redundancy)</td>
					<td>Answers from cache, otherwise looks the name up, validates DNSSEC and caches the result</td>
			</tr>
			<tr>
					<td>Root, TLD and authoritative servers</td>
					<td>Internet</td>
					<td>Return referrals and final answers</td>
			</tr>
	</tbody>
</table>
<p>The flow: client asks the resolver → cache hit? answer straight away → otherwise root → TLD → authoritative server → validate → cache → answer.</p>
<h2 id="installation">Installation <a class="anchor" data-pagefind-ignore href="#installation" aria-label="Link to this section">#</a></h2>
<p>The packages install the server, the <code>named-checkconf</code> tool and <code>dig</code>. Enabling the service now means it also starts at boot.</p>
<p><strong>Debian/Ubuntu:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo apt update
</span></span><span class="line"><span class="cl">sudo apt install -y bind9 bind9utils bind9-doc dnsutils
</span></span></code></pre></div><p><strong>RHEL/Rocky/AlmaLinux:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo dnf install -y <span class="nb">bind</span> bind-utils
</span></span></code></pre></div><p>Enable and start the service:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo systemctl <span class="nb">enable</span> --now named
</span></span></code></pre></div><h2 id="basic-configuration">Basic Configuration <a class="anchor" data-pagefind-ignore href="#basic-configuration" aria-label="Link to this section">#</a></h2>
<p>The main configuration file is <code>/etc/bind/named.conf</code> (Debian) or <code>/etc/named.conf</code> (RHEL). The resolver settings go in the <code>options</code> block.</p>
<h3 id="define-access-control-lists">Define Access Control Lists <a class="anchor" data-pagefind-ignore href="#define-access-control-lists" aria-label="Link to this section">#</a></h3>
<p>An open resolver gets abused for amplification attacks within days. The <code>trusted</code> ACL names the networks that may use it; the options refer to it. Create or edit <code>/etc/bind/named.conf.options</code>:</p>
<ul>
<li><code>allow-recursion</code>, <code>allow-query</code>, <code>allow-query-cache</code> <code>{ trusted; }</code>: only trusted clients may query, recurse, or read the cache.</li>
<li><code>allow-transfer { none; }</code>: a resolver hosts no zones to transfer.</li>
<li><code>dnssec-validation auto</code>: validate signed answers with the built-in root trust anchor.</li>
<li><code>max-cache-size</code>: memory cap for the cache. Raise it for many clients.</li>
<li><code>max-cache-ttl</code> / <code>max-ncache-ttl</code>: upper limits for how long positive and negative (NXDOMAIN) answers are cached.</li>
<li><code>minimal-responses yes</code> and <code>version &quot;not disclosed&quot;</code>: smaller answers, no version leak.</li>
<li><code>querylog no</code>: query logging is off by default; it is noisy. Turn it on with <code>rndc querylog</code> when debugging.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bind" data-lang="bind"><span class="line"><span class="cl"><span class="err">//</span><span class="w"> </span><span class="err">Define</span><span class="w"> </span><span class="err">trusted</span><span class="w"> </span><span class="err">networks</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">acl</span><span class="w"> </span><span class="err">&#34;trusted&#34;</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">localhost</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">localnets</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="mi">192.168.0.0</span><span class="err">/</span><span class="sc">16</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="mi">10.0.0.0</span><span class="err">/</span><span class="sc">8</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="mi">172.16.0.0</span><span class="err">/</span><span class="sc">12</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">options</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">directory</span><span class="w"> </span><span class="err">&#34;/var/cache/bind&#34;</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Network</span><span class="w"> </span><span class="err">interface</span><span class="w"> </span><span class="err">settings</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">listen-on</span><span class="w"> </span><span class="err">port</span><span class="w"> </span><span class="sc">53</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">any</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">listen-on-v6</span><span class="w"> </span><span class="err">port</span><span class="w"> </span><span class="sc">53</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">any</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Recursion</span><span class="w"> </span><span class="err">settings</span><span class="w"> </span><span class="err">-</span><span class="w"> </span><span class="err">CRITICAL</span><span class="w"> </span><span class="err">for</span><span class="w"> </span><span class="err">security</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">recursion</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">allow-recursion</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">trusted</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">allow-query</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">trusted</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">allow-query-cache</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">trusted</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Disable</span><span class="w"> </span><span class="err">zone</span><span class="w"> </span><span class="err">transfers</span><span class="w"> </span><span class="p">(</span><span class="err">not</span><span class="w"> </span><span class="err">needed</span><span class="w"> </span><span class="err">for</span><span class="w"> </span><span class="err">resolver</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">allow-transfer</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">none</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">DNSSEC</span><span class="w"> </span><span class="err">validation</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">dnssec-validation</span><span class="w"> </span><span class="err">auto</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Source</span><span class="w"> </span><span class="err">port</span><span class="w"> </span><span class="err">randomization</span><span class="w"> </span><span class="err">is</span><span class="w"> </span><span class="err">on</span><span class="w"> </span><span class="err">by</span><span class="w"> </span><span class="err">default</span><span class="w"> </span><span class="err">-</span><span class="w"> </span><span class="err">don&#39;t</span><span class="w"> </span><span class="err">set</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">query-source</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="err">port</span><span class="w"> </span><span class="p">(</span><span class="err">the</span><span class="w"> </span><span class="err">&#39;port&#39;</span><span class="w"> </span><span class="err">token</span><span class="w"> </span><span class="err">is</span><span class="w"> </span><span class="err">deprecated</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Performance</span><span class="w"> </span><span class="err">tuning</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">max-cache-size</span><span class="w"> </span><span class="sc">256m</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">max-cache-ttl</span><span class="w"> </span><span class="sc">86400</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">max-ncache-ttl</span><span class="w"> </span><span class="sc">3600</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Prevent</span><span class="w"> </span><span class="err">amplification</span><span class="w"> </span><span class="err">attacks</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">minimal-responses</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Hide</span><span class="w"> </span><span class="err">version</span><span class="w"> </span><span class="err">string</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">version</span><span class="w"> </span><span class="err">&#34;not</span><span class="w"> </span><span class="err">disclosed&#34;</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Logging</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">querylog</span><span class="w"> </span><span class="err">no</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span></code></pre></div><h3 id="security-hardening">Security Hardening <a class="anchor" data-pagefind-ignore href="#security-hardening" aria-label="Link to this section">#</a></h3>
<p>These options go into the same <code>options</code> block and limit what the resolver will answer.</p>
<ul>
<li><code>deny-answer-addresses</code>: drop answers from the internet that point at loopback addresses, a defence against DNS rebinding.</li>
<li><code>rate-limit</code>: Response Rate Limiting caps identical responses per client, so the resolver is a poor amplifier.</li>
<li><code>empty-zones-enable yes</code>: answer reverse lookups for private and reserved ranges locally instead of leaking them upstream.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bind" data-lang="bind"><span class="line"><span class="cl"><span class="nc">options</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="err">previous</span><span class="w"> </span><span class="err">options</span><span class="w"> </span><span class="err">...</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Prevent</span><span class="w"> </span><span class="err">loopback/localhost</span><span class="w"> </span><span class="err">attacks</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">deny-answer-addresses</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="mi">127.0.0.0</span><span class="err">/</span><span class="sc">8</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">::</span><span class="sc">1</span><span class="err">/</span><span class="sc">128</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">}</span><span class="w"> </span><span class="err">except-from</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">&#34;none&#34;</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Rate</span><span class="w"> </span><span class="err">limiting</span><span class="w"> </span><span class="err">to</span><span class="w"> </span><span class="err">prevent</span><span class="w"> </span><span class="err">abuse</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">rate-limit</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">responses-per-second</span><span class="w"> </span><span class="sc">10</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">window</span><span class="w"> </span><span class="sc">5</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Keep</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">built-in</span><span class="w"> </span><span class="err">empty</span><span class="w"> </span><span class="err">zones</span><span class="w"> </span><span class="err">for</span><span class="w"> </span><span class="err">RFC</span><span class="w"> </span><span class="sc">1918</span><span class="w"> </span><span class="err">and</span><span class="w"> </span><span class="err">other</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">reserved</span><span class="w"> </span><span class="err">reverse</span><span class="w"> </span><span class="err">ranges</span><span class="w"> </span><span class="p">(</span><span class="err">stops</span><span class="w"> </span><span class="err">those</span><span class="w"> </span><span class="err">queries</span><span class="w"> </span><span class="err">leaking</span><span class="w"> </span><span class="err">upstream</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">empty-zones-enable</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span></code></pre></div><h2 id="forwarding-configuration-optional">Forwarding Configuration (Optional) <a class="anchor" data-pagefind-ignore href="#forwarding-configuration-optional" aria-label="Link to this section">#</a></h2>
<p>By default the resolver does full recursion from the root. Forwarders send cache misses to upstream resolvers instead, which helps when outbound DNS is restricted to a few servers.</p>
<table>
	<thead>
			<tr>
					<th>Mode</th>
					<th>Behaviour</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>No forwarders</td>
					<td>Full recursion from the root</td>
					<td>Most setups; no third party sees your queries</td>
			</tr>
			<tr>
					<td><code>forward first</code></td>
					<td>Ask forwarders, recurse yourself if they fail</td>
					<td>Upstream preferred, with a fallback</td>
			</tr>
			<tr>
					<td><code>forward only</code></td>
					<td>Only ask forwarders</td>
					<td>Networks where outbound DNS must go through specific servers</td>
			</tr>
	</tbody>
</table>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bind" data-lang="bind"><span class="line"><span class="cl"><span class="nc">options</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">...</span><span class="w"> </span><span class="err">previous</span><span class="w"> </span><span class="err">options</span><span class="w"> </span><span class="err">...</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Forward</span><span class="w"> </span><span class="err">to</span><span class="w"> </span><span class="err">upstream</span><span class="w"> </span><span class="err">resolvers</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">forwarders</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="mi">1.1.1.1</span><span class="c">;        // Cloudflare</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="mi">8.8.8.8</span><span class="c">;        // Google</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="mi">9.9.9.9</span><span class="c">;        // Quad9</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">//</span><span class="w"> </span><span class="err">Forward</span><span class="w"> </span><span class="err">first,</span><span class="w"> </span><span class="err">then</span><span class="w"> </span><span class="err">recurse</span><span class="w"> </span><span class="err">if</span><span class="w"> </span><span class="err">forwarders</span><span class="w"> </span><span class="err">fail</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">forward</span><span class="w"> </span><span class="err">first</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span></code></pre></div><p>Use <code>forward only;</code> if you want to exclusively use forwarders without fallback recursion.</p>
<h2 id="logging-configuration">Logging Configuration <a class="anchor" data-pagefind-ignore href="#logging-configuration" aria-label="Link to this section">#</a></h2>
<p>Separate channels keep queries, security events and general messages apart. Add to your configuration:</p>
<table>
	<thead>
			<tr>
					<th>Channel</th>
					<th>Categories</th>
					<th>What you find there</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>default_log</code></td>
					<td><code>default</code></td>
					<td>Startup, errors, general messages</td>
			</tr>
			<tr>
					<td><code>query_log</code></td>
					<td><code>queries</code></td>
					<td>Every query, once query logging is on</td>
			</tr>
			<tr>
					<td><code>security_log</code></td>
					<td><code>security</code>, <code>client</code></td>
					<td>Denied queries and client problems</td>
			</tr>
	</tbody>
</table>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bind" data-lang="bind"><span class="line"><span class="cl"><span class="nc">logging</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">channel</span><span class="w"> </span><span class="err">default_log</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">file</span><span class="w"> </span><span class="err">&#34;/var/log/named/</span><span class="nc">default.log</span><span class="err">&#34;</span><span class="w"> </span><span class="err">versions</span><span class="w"> </span><span class="sc">3</span><span class="w"> </span><span class="err">size</span><span class="w"> </span><span class="sc">5m</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">severity</span><span class="w"> </span><span class="err">info</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">print-time</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">print-severity</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">print-category</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">channel</span><span class="w"> </span><span class="err">query_log</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">file</span><span class="w"> </span><span class="err">&#34;/var/log/named/</span><span class="nc">query.log</span><span class="err">&#34;</span><span class="w"> </span><span class="err">versions</span><span class="w"> </span><span class="sc">5</span><span class="w"> </span><span class="err">size</span><span class="w"> </span><span class="sc">10m</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">severity</span><span class="w"> </span><span class="err">info</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">print-time</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">channel</span><span class="w"> </span><span class="err">security_log</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">file</span><span class="w"> </span><span class="err">&#34;/var/log/named/</span><span class="nc">security.log</span><span class="err">&#34;</span><span class="w"> </span><span class="err">versions</span><span class="w"> </span><span class="sc">3</span><span class="w"> </span><span class="err">size</span><span class="w"> </span><span class="sc">5m</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">severity</span><span class="w"> </span><span class="err">info</span><span class="c">;    // denied queries are logged at info</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">print-time</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">print-severity</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">category</span><span class="w"> </span><span class="err">default</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">default_log</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">category</span><span class="w"> </span><span class="err">queries</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">query_log</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">category</span><span class="w"> </span><span class="err">security</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">security_log</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">category</span><span class="w"> </span><span class="err">client</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">security_log</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span></code></pre></div><p>Create the log directory, owned by the BIND user, before restarting:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo mkdir -p /var/log/named
</span></span><span class="line"><span class="cl">sudo chown bind:bind /var/log/named
</span></span></code></pre></div><h2 id="root-hints">Root Hints <a class="anchor" data-pagefind-ignore href="#root-hints" aria-label="Link to this section">#</a></h2>
<p>Root hints tell the resolver where the root servers are, the starting point for every recursion. BIND usually includes these, but you can download the current list:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo curl -o /var/cache/bind/named.root https://www.internic.net/domain/named.root
</span></span></code></pre></div><p>Both Debian/Ubuntu and RHEL already define the hint zone: Debian/Ubuntu in <code>/etc/bind/named.conf.default-zones</code> (pointing at <code>/usr/share/dns/root.hints</code>), RHEL in <code>/etc/named.conf</code> (<code>named.ca</code>). Don&rsquo;t add a second <code>zone &quot;.&quot;</code>, because <code>named-checkconf</code> rejects it with <code>zone '.': already exists</code>. Instead, change the <code>file</code> line of the existing hint zone:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bind" data-lang="bind"><span class="line"><span class="cl"><span class="nc">zone</span><span class="w"> </span><span class="err">&#34;.&#34;</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">type</span><span class="w"> </span><span class="err">hint</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">file</span><span class="w"> </span><span class="err">&#34;/var/cache/bind/</span><span class="nc">named.root</span><span class="err">&#34;</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span></code></pre></div><h2 id="validate-and-start">Validate and Start <a class="anchor" data-pagefind-ignore href="#validate-and-start" aria-label="Link to this section">#</a></h2>
<p>Always check the configuration first: a restart with a broken configuration leaves your clients without DNS.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo named-checkconf
</span></span></code></pre></div><p>If there are no errors, restart BIND:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo systemctl restart named
</span></span></code></pre></div><p>Check the status:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo systemctl status named
</span></span><span class="line"><span class="cl">sudo journalctl -u named -f
</span></span></code></pre></div><h2 id="testing">Testing <a class="anchor" data-pagefind-ignore href="#testing" aria-label="Link to this section">#</a></h2>
<p>Test from a client machine on a trusted network. Each check proves one part of the setup:</p>
<ul>
<li><code>google.com</code>: recursion and caching work.</li>
<li><code>dnssec-failed.org</code>: a deliberately broken DNSSEC domain. SERVFAIL proves validation is on.</li>
<li><code>version.bind</code>: should return &ldquo;not disclosed&rdquo;.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Test basic resolution</span>
</span></span><span class="line"><span class="cl">dig @your-resolver-ip google.com
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test DNSSEC validation</span>
</span></span><span class="line"><span class="cl">dig @your-resolver-ip dnssec-failed.org
</span></span><span class="line"><span class="cl"><span class="c1"># Should return SERVFAIL (DNSSEC validation failure)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check that the version string is hidden (&#34;not disclosed&#34;)</span>
</span></span><span class="line"><span class="cl">dig @your-resolver-ip +short version.bind txt chaos
</span></span></code></pre></div><p>The DNS-OARC port randomization test (<code>porttest.dns-oarc.net</code>) that older guides mention has been retired; the name now returns NXDOMAIN. BIND randomizes query source ports by default, so there is nothing to enable as long as you don&rsquo;t pin <code>query-source</code> to a fixed port.</p>
<h2 id="firewall-configuration">Firewall Configuration <a class="anchor" data-pagefind-ignore href="#firewall-configuration" aria-label="Link to this section">#</a></h2>
<p>The firewall is a second line behind the ACL: only trusted networks reach port 53. DNS uses both UDP and TCP.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># UFW (Ubuntu)</span>
</span></span><span class="line"><span class="cl">sudo ufw allow from 192.168.0.0/16 to any port <span class="m">53</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># firewalld (RHEL)</span>
</span></span><span class="line"><span class="cl">sudo firewall-cmd --permanent --add-service<span class="o">=</span>dns
</span></span><span class="line"><span class="cl">sudo firewall-cmd --reload
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># iptables</span>
</span></span><span class="line"><span class="cl">sudo iptables -A INPUT -p udp --dport <span class="m">53</span> -s 192.168.0.0/16 -j ACCEPT
</span></span><span class="line"><span class="cl">sudo iptables -A INPUT -p tcp --dport <span class="m">53</span> -s 192.168.0.0/16 -j ACCEPT
</span></span></code></pre></div><h2 id="complete-configuration-example">Complete Configuration Example <a class="anchor" data-pagefind-ignore href="#complete-configuration-example" aria-label="Link to this section">#</a></h2>
<p>All of the above in one <code>/etc/bind/named.conf.options</code>, for reference:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bind" data-lang="bind"><span class="line"><span class="cl"><span class="nc">acl</span><span class="w"> </span><span class="err">&#34;trusted&#34;</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">localhost</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">localnets</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="mi">192.168.0.0</span><span class="err">/</span><span class="sc">16</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="mi">10.0.0.0</span><span class="err">/</span><span class="sc">8</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">options</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">directory</span><span class="w"> </span><span class="err">&#34;/var/cache/bind&#34;</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">listen-on</span><span class="w"> </span><span class="err">port</span><span class="w"> </span><span class="sc">53</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">any</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">listen-on-v6</span><span class="w"> </span><span class="err">port</span><span class="w"> </span><span class="sc">53</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">any</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">recursion</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">allow-recursion</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">trusted</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">allow-query</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">trusted</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">allow-query-cache</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">trusted</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">allow-transfer</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">none</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">dnssec-validation</span><span class="w"> </span><span class="err">auto</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">max-cache-size</span><span class="w"> </span><span class="sc">256m</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">max-cache-ttl</span><span class="w"> </span><span class="sc">86400</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">max-ncache-ttl</span><span class="w"> </span><span class="sc">3600</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">minimal-responses</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">version</span><span class="w"> </span><span class="err">&#34;not</span><span class="w"> </span><span class="err">disclosed&#34;</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">deny-answer-addresses</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="mi">127.0.0.0</span><span class="err">/</span><span class="sc">8</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">::</span><span class="sc">1</span><span class="err">/</span><span class="sc">128</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">}</span><span class="w"> </span><span class="err">except-from</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">&#34;none&#34;</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">rate-limit</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">responses-per-second</span><span class="w"> </span><span class="sc">10</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">window</span><span class="w"> </span><span class="sc">5</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">logging</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">channel</span><span class="w"> </span><span class="err">default_log</span><span class="w"> </span><span class="err">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">file</span><span class="w"> </span><span class="err">&#34;/var/log/named/</span><span class="nc">default.log</span><span class="err">&#34;</span><span class="w"> </span><span class="err">versions</span><span class="w"> </span><span class="sc">3</span><span class="w"> </span><span class="err">size</span><span class="w"> </span><span class="sc">5m</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">severity</span><span class="w"> </span><span class="err">info</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">print-time</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="err">print-severity</span><span class="w"> </span><span class="err">yes</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">category</span><span class="w"> </span><span class="err">default</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">default_log</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="err">}</span><span class="c">;</span><span class="w">
</span></span></span></code></pre></div><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Likely cause / fix</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Clients get <code>REFUSED</code></td>
					<td>Client network missing from the <code>trusted</code> ACL</td>
			</tr>
			<tr>
					<td><code>named</code> fails to start after adding logging</td>
					<td><code>/var/log/named</code> missing or wrong owner</td>
			</tr>
			<tr>
					<td><code>zone '.': already exists</code></td>
					<td>A second root hint zone was added; edit the existing one</td>
			</tr>
			<tr>
					<td>Valid domains return SERVFAIL</td>
					<td>DNSSEC failure or no outbound DNS; check <code>security.log</code> and the firewall</td>
			</tr>
	</tbody>
</table>
<h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub:
<a href="https://github.com/pderuiter/blog-bind-recursive-resolver" rel="noopener">pderuiter/blog-bind-recursive-resolver</a>. It creates an Ubuntu 24.04 VM on Proxmox and configures the resolver from this post, with the trusted ACL, hardening, logging, fresh root hints and optional forwarders; fill in <code>terraform.tfvars</code>, run <code>terraform apply</code>, then <code>ansible-playbook site.yml</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>You now have a secure BIND recursive resolver. Key points to remember:</p>
<ul>
<li><strong>Never run an open resolver</strong>: always restrict access with ACLs.</li>
<li><strong>Enable DNSSEC validation</strong>: protects against cache poisoning.</li>
<li><strong>Use rate limiting</strong>: prevents amplification attacks.</li>
<li><strong>Monitor logs</strong>: watch for unusual activity.</li>
<li><strong>Keep BIND updated</strong>: security patches are released regularly.</li>
</ul>
<p>In the next posts, we&rsquo;ll cover setting up BIND as an <a href="https://blog.bsdserver.nl/how-to-setup-bind-as-an-authoritative-dns-server/">authoritative server</a>, configuring DNSSEC, and implementing DNS over TLS/HTTPS.</p>
]]></content:encoded></item><item><title>Provisioning TLS Certificates with Traefik, cert-manager, and ACME-DNS in Kubernetes</title><link>https://blog.bsdserver.nl/provisioning-tls-certificates-with-traefik-cert-manager-and-acme-dns-in-kubernetes/</link><guid isPermaLink="false">693b526b79eb54000160a4d3</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Thu, 11 Dec 2025 23:23:23 +0000</pubDate><description>Introduction In a Kubernetes environment, having a robust and secure ingress controller is critical to properly route traffic to your applications.</description><category>Kubernetes</category><category>Traefik</category><category>cert-manager</category><category>Security</category><category>DevOps</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/tls-traefik-k8s-cert-manager-acme-dns.png" medium="image"/><content:encoded><![CDATA[<p>In Kubernetes, every Ingress with a hostname needs a TLS certificate, and doing that by hand does not scale. A DNS-01 challenge is the most flexible way to get Let&rsquo;s Encrypt certificates, but it usually means giving cert-manager API credentials that can change your whole DNS zone.</p>
<p>This post builds Traefik as the ingress controller, cert-manager to issue and renew certificates, and ACME-DNS: a small DNS server that only answers ACME challenges. cert-manager only gets credentials for ACME-DNS, never for your main DNS.</p>
<h2 id="why-this-stack">Why this stack? <a class="anchor" data-pagefind-ignore href="#why-this-stack" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Why</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><strong>Traefik</strong></td>
					<td>Simple ingress controller; handles standard Ingress objects and its own CRDs, applies changes without restarts.</td>
			</tr>
			<tr>
					<td><strong>cert-manager</strong></td>
					<td>Issues and renews certificates via ACME, stores them as Kubernetes secrets.</td>
			</tr>
			<tr>
					<td><strong>ACME-DNS</strong></td>
					<td>Solves DNS-01 challenges without credentials for your main DNS zone.</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 you need DNS-01 (wildcards, hosts not reachable from the internet) and your DNS provider has no API, no cert-manager support, or only all-or-nothing API keys.</li>
<li><strong>Skip it</strong> when HTTP-01 works for you, or your DNS provider has a scoped API token that cert-manager supports directly. ACME-DNS is one more public DNS server to run.</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>Traefik</td>
					<td>Cluster, namespace <code>traefik</code></td>
					<td>Ingress controller: terminates TLS with the certificate secret, routes to services.</td>
			</tr>
			<tr>
					<td>cert-manager</td>
					<td>Cluster, namespace <code>cert-manager</code></td>
					<td>Watches Certificate resources, runs the ACME order, writes the TLS secret.</td>
			</tr>
			<tr>
					<td>ACME-DNS</td>
					<td>Cluster, namespace <code>acme-dns</code></td>
					<td>Authoritative DNS for <code>auth.example.com</code> (public, port 53); HTTP API for updating TXT records (cluster-internal).</td>
			</tr>
			<tr>
					<td>Main DNS</td>
					<td>Your DNS provider</td>
					<td>Delegates <code>auth.example.com</code> to ACME-DNS; CNAMEs <code>_acme-challenge.example.com</code> into it.</td>
			</tr>
	</tbody>
</table>
<p>The flow: a Certificate is created → cert-manager asks Let&rsquo;s Encrypt for an order → writes the challenge TXT record into ACME-DNS through its API → Let&rsquo;s Encrypt looks up <code>_acme-challenge.example.com</code> → follows the CNAME to ACME-DNS → validates → cert-manager stores the certificate in a secret → Traefik serves it.</p>
<h2 id="1-installing-traefik">1. Installing Traefik <a class="anchor" data-pagefind-ignore href="#1-installing-traefik" aria-label="Link to this section">#</a></h2>
<p>Traefik is the ingress controller that will serve the certificates. The Helm chart gives it a LoadBalancer Service for incoming traffic.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">helm repo add traefik https://helm.traefik.io/traefik
</span></span><span class="line"><span class="cl">helm repo update
</span></span><span class="line"><span class="cl">kubectl create namespace traefik
</span></span><span class="line"><span class="cl">helm install traefik traefik/traefik --namespace traefik --set service.spec.type<span class="o">=</span>LoadBalancer
</span></span></code></pre></div><p>Current chart versions validate their values against a schema, and the old <code>service.type</code> key is rejected with <code>at '/service': additional properties 'type' not allowed</code>. The Service type now lives under <code>service.spec</code>. <code>LoadBalancer</code> is the default anyway.</p>
<p>Check that the pod runs and the Service has an external IP:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">kubectl get pods -n traefik
</span></span><span class="line"><span class="cl">kubectl get svc -n traefik
</span></span></code></pre></div><h2 id="2-installing-cert-manager">2. Installing cert-manager <a class="anchor" data-pagefind-ignore href="#2-installing-cert-manager" aria-label="Link to this section">#</a></h2>
<p>cert-manager runs the ACME orders and renewals. <code>crds.enabled=true</code> installs its CRDs (Certificate, ClusterIssuer, &hellip;) together with the chart.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">helm repo add jetstack https://charts.jetstack.io
</span></span><span class="line"><span class="cl">helm repo update
</span></span><span class="line"><span class="cl">kubectl create namespace cert-manager
</span></span><span class="line"><span class="cl">helm install cert-manager jetstack/cert-manager --namespace cert-manager --set crds.enabled<span class="o">=</span><span class="nb">true</span>
</span></span></code></pre></div><p>Check that the pods are running:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">kubectl get pods -n cert-manager
</span></span></code></pre></div><h2 id="3-installing-acme-dns">3. Installing ACME-DNS <a class="anchor" data-pagefind-ignore href="#3-installing-acme-dns" aria-label="Link to this section">#</a></h2>
<p>ACME-DNS answers DNS queries for one subdomain and lets clients update TXT records in it through an HTTP API. Each registered account can only update its own record.</p>
<p>ACME-DNS reads its settings from <code>/etc/acme-dns/config.cfg</code> and won&rsquo;t start without it (<code>configuration file not found</code>); there are no environment variables for this. The manifest below:</p>
<ul>
<li><strong>ConfigMap</strong>: the config file, mounted at <code>/etc/acme-dns</code>.</li>
<li><strong>PersistentVolumeClaim</strong>: the SQLite database, which holds the registered accounts. Losing it breaks every CNAME you created.</li>
<li><strong>Deployment</strong>: one replica, <code>Recreate</code> strategy, so the old pod releases the volume before the new one starts.</li>
<li><strong>Service <code>acme-dns-dns</code></strong>: LoadBalancer, DNS on port 53 UDP and TCP, reachable from the internet.</li>
<li><strong>Service <code>acme-dns</code></strong>: ClusterIP, the HTTP API, only reachable inside the cluster.</li>
</ul>
<p>Key settings in <code>config.cfg</code>:</p>
<table>
	<thead>
			<tr>
					<th>Setting</th>
					<th>What it does</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>domain</code>, <code>nsname</code></td>
					<td>The subdomain ACME-DNS is authoritative for, and its name server name.</td>
			</tr>
			<tr>
					<td><code>records</code></td>
					<td>Static records it serves: its own A and NS records. Fill in the public IP.</td>
			</tr>
			<tr>
					<td><code>protocol = &quot;both&quot;</code></td>
					<td>Answer DNS over UDP and TCP.</td>
			</tr>
			<tr>
					<td><code>[api] tls = &quot;none&quot;</code></td>
					<td>Plain HTTP; acceptable because the API Service is cluster-internal.</td>
			</tr>
			<tr>
					<td><code>disable_registration = false</code></td>
					<td>Anyone who reaches the API can register an account. Needed for the registration step below.</td>
			</tr>
	</tbody>
</table>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">kubectl create namespace acme-dns
</span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">apiVersion</span><span class="p">:</span><span class="w"> </span><span class="l">v1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l">ConfigMap</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">acme-dns-config</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">namespace</span><span class="p">:</span><span class="w"> </span><span class="l">acme-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">data</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">config.cfg</span><span class="p">:</span><span class="w"> </span><span class="p">|</span><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">    [general]
</span></span></span><span class="line"><span class="cl"><span class="sd">    listen = &#34;0.0.0.0:53&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">    protocol = &#34;both&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">    domain = &#34;auth.example.com&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">    nsname = &#34;ns1.auth.example.com&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">    nsadmin = &#34;admin.example.com&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">    records = [
</span></span></span><span class="line"><span class="cl"><span class="sd">        &#34;auth.example.com. A &lt;PUBLIC_IP_OF_ACME_DNS&gt;&#34;,
</span></span></span><span class="line"><span class="cl"><span class="sd">        &#34;ns1.auth.example.com. A &lt;PUBLIC_IP_OF_ACME_DNS&gt;&#34;,
</span></span></span><span class="line"><span class="cl"><span class="sd">        &#34;auth.example.com. NS ns1.auth.example.com.&#34;,
</span></span></span><span class="line"><span class="cl"><span class="sd">    ]
</span></span></span><span class="line"><span class="cl"><span class="sd">    [database]
</span></span></span><span class="line"><span class="cl"><span class="sd">    engine = &#34;sqlite&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">    connection = &#34;/var/lib/acme-dns/acme-dns.db&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">    [api]
</span></span></span><span class="line"><span class="cl"><span class="sd">    ip = &#34;0.0.0.0&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">    port = &#34;80&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">    tls = &#34;none&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">    disable_registration = false
</span></span></span><span class="line"><span class="cl"><span class="sd">    corsorigins = [&#34;*&#34;]
</span></span></span><span class="line"><span class="cl"><span class="sd">    use_header = false
</span></span></span><span class="line"><span class="cl"><span class="sd">    header_name = &#34;X-Forwarded-For&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">    [logconfig]
</span></span></span><span class="line"><span class="cl"><span class="sd">    loglevel = &#34;info&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">    logtype = &#34;stdout&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">    logformat = &#34;text&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nn">---</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">apiVersion</span><span class="p">:</span><span class="w"> </span><span class="l">v1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l">PersistentVolumeClaim</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">acme-dns-data</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">namespace</span><span class="p">:</span><span class="w"> </span><span class="l">acme-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">spec</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">accessModes</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;ReadWriteOnce&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">resources</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">requests</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">storage</span><span class="p">:</span><span class="w"> </span><span class="l">100Mi</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nn">---</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">apiVersion</span><span class="p">:</span><span class="w"> </span><span class="l">apps/v1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l">Deployment</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">acme-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">namespace</span><span class="p">:</span><span class="w"> </span><span class="l">acme-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">spec</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">replicas</span><span class="p">:</span><span class="w"> </span><span class="m">1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">strategy</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">type</span><span class="p">:</span><span class="w"> </span><span class="l">Recreate</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">selector</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">matchLabels</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">app</span><span class="p">:</span><span class="w"> </span><span class="l">acme-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">template</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">labels</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">app</span><span class="p">:</span><span class="w"> </span><span class="l">acme-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">spec</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">containers</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">acme-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l">joohoi/acme-dns:v2.0.2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">ports</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- <span class="nt">containerPort</span><span class="p">:</span><span class="w"> </span><span class="m">53</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">protocol</span><span class="p">:</span><span class="w"> </span><span class="l">UDP</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- <span class="nt">containerPort</span><span class="p">:</span><span class="w"> </span><span class="m">53</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">protocol</span><span class="p">:</span><span class="w"> </span><span class="l">TCP</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- <span class="nt">containerPort</span><span class="p">:</span><span class="w"> </span><span class="m">80</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">protocol</span><span class="p">:</span><span class="w"> </span><span class="l">TCP</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">volumeMounts</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">config</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">mountPath</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/acme-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">readOnly</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">data</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">mountPath</span><span class="p">:</span><span class="w"> </span><span class="l">/var/lib/acme-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">volumes</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">config</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">configMap</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">acme-dns-config</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">data</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">persistentVolumeClaim</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">claimName</span><span class="p">:</span><span class="w"> </span><span class="l">acme-dns-data</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nn">---</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># DNS, reachable from the internet</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">apiVersion</span><span class="p">:</span><span class="w"> </span><span class="l">v1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l">Service</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">acme-dns-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">namespace</span><span class="p">:</span><span class="w"> </span><span class="l">acme-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">spec</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">type</span><span class="p">:</span><span class="w"> </span><span class="l">LoadBalancer</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">selector</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">app</span><span class="p">:</span><span class="w"> </span><span class="l">acme-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ports</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">dns-udp</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">port</span><span class="p">:</span><span class="w"> </span><span class="m">53</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">protocol</span><span class="p">:</span><span class="w"> </span><span class="l">UDP</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">dns-tcp</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">port</span><span class="p">:</span><span class="w"> </span><span class="m">53</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">protocol</span><span class="p">:</span><span class="w"> </span><span class="l">TCP</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nn">---</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># HTTP API, cluster-internal only</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">apiVersion</span><span class="p">:</span><span class="w"> </span><span class="l">v1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l">Service</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">acme-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">namespace</span><span class="p">:</span><span class="w"> </span><span class="l">acme-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">spec</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">selector</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">app</span><span class="p">:</span><span class="w"> </span><span class="l">acme-dns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ports</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">api</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">port</span><span class="p">:</span><span class="w"> </span><span class="m">80</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">protocol</span><span class="p">:</span><span class="w"> </span><span class="l">TCP</span><span class="w">
</span></span></span></code></pre></div><p><code>&lt;PUBLIC_IP_OF_ACME_DNS&gt;</code> is the external IP the <code>acme-dns-dns</code> LoadBalancer gets.</p>
<h2 id="4-dns-configuration-for-subdomain-delegation">4. DNS Configuration for Subdomain Delegation <a class="anchor" data-pagefind-ignore href="#4-dns-configuration-for-subdomain-delegation" aria-label="Link to this section">#</a></h2>
<p>Let&rsquo;s Encrypt looks for the challenge at <code>_acme-challenge.example.com</code> in your main DNS. You delegate a subdomain (<code>auth.example.com</code>) to ACME-DNS once, and point <code>_acme-challenge</code> at it with a CNAME per domain.</p>
<p>Why a CNAME and not an NS record on <code>_acme-challenge.example.com</code> itself: ACME-DNS only answers for names under its own domain, so it would answer NXDOMAIN.</p>
<p><strong>In your main DNS</strong>, delegate <code>auth.example.com</code> to ACME-DNS, with a glue record:</p>
<pre tabindex="0"><code>auth.example.com.             IN NS    ns1.auth.example.com.
ns1.auth.example.com.         IN A     &lt;PUBLIC_IP_OF_ACME_DNS&gt;
</code></pre><p><strong>Register an account</strong> for each domain you want certificates for. The API is only reachable inside the cluster, so use a port-forward:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">kubectl -n acme-dns port-forward svc/acme-dns 8080:80 <span class="p">&amp;</span>
</span></span><span class="line"><span class="cl">curl -s -X POST http://localhost:8080/register &gt; acme-dns-account.json
</span></span><span class="line"><span class="cl">cat acme-dns-account.json
</span></span></code></pre></div><p>The response contains a <code>username</code>, <code>password</code> and a <code>fulldomain</code> such as <code>4411d03a-5aaa-419b-9bc9-a5d55a94c8df.auth.example.com</code>.</p>
<p><strong>In your main DNS</strong>, point the challenge name at that <code>fulldomain</code>:</p>
<pre tabindex="0"><code>_acme-challenge.example.com.  IN CNAME 4411d03a-5aaa-419b-9bc9-a5d55a94c8df.auth.example.com.
</code></pre><h2 id="5-configuring-cert-manager-for-acme-dns">5. Configuring cert-manager for ACME-DNS <a class="anchor" data-pagefind-ignore href="#5-configuring-cert-manager-for-acme-dns" aria-label="Link to this section">#</a></h2>
<p>cert-manager needs the account credentials to update the TXT record. It expects them as a JSON map keyed by the domain name. For a ClusterIssuer, the secret goes in the <code>cert-manager</code> namespace:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">jq <span class="s1">&#39;{&#34;example.com&#34;: .}&#39;</span> acme-dns-account.json &gt; account.json
</span></span><span class="line"><span class="cl">kubectl -n cert-manager create secret generic acmedns-secret --from-file<span class="o">=</span>account.json
</span></span></code></pre></div><p>A ClusterIssuer can issue certificates in every namespace. The important fields:</p>
<ul>
<li><code>server</code>: the Let&rsquo;s Encrypt production endpoint. Use the staging URL while testing to avoid rate limits.</li>
<li><code>privateKeySecretRef</code>: where cert-manager stores the Let&rsquo;s Encrypt account key; created automatically.</li>
<li><code>acmeDNS.host</code>: the cluster-internal API Service from step 3.</li>
<li><code>accountSecretRef</code>: the secret you just created.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">apiVersion</span><span class="p">:</span><span class="w"> </span><span class="l">cert-manager.io/v1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l">ClusterIssuer</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">letsencrypt-acmedns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">spec</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">acme</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">server</span><span class="p">:</span><span class="w"> </span><span class="l">https://acme-v02.api.letsencrypt.org/directory</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">email</span><span class="p">:</span><span class="w"> </span><span class="l">your-email@example.com</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">privateKeySecretRef</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">acmedns-issuer-account-key</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">solvers</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">dns01</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">acmeDNS</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">host</span><span class="p">:</span><span class="w"> </span><span class="l">http://acme-dns.acme-dns.svc.cluster.local</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">accountSecretRef</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">acmedns-secret</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">key</span><span class="p">:</span><span class="w"> </span><span class="l">account.json</span><span class="w">
</span></span></span></code></pre></div><h3 id="requesting-a-certificate">Requesting a Certificate <a class="anchor" data-pagefind-ignore href="#requesting-a-certificate" aria-label="Link to this section">#</a></h3>
<p>A Certificate resource tells cert-manager which names to cover and which secret to write. cert-manager renews it before it expires.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">apiVersion</span><span class="p">:</span><span class="w"> </span><span class="l">cert-manager.io/v1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l">Certificate</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">example-com-tls</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">namespace</span><span class="p">:</span><span class="w"> </span><span class="l">default</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">spec</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">secretName</span><span class="p">:</span><span class="w"> </span><span class="l">example-com-tls-secret</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">issuerRef</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">letsencrypt-acmedns</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l">ClusterIssuer</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">dnsNames</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="l">example.com</span><span class="w">
</span></span></span></code></pre></div><h2 id="6-using-tls-in-traefik">6. Using TLS in Traefik <a class="anchor" data-pagefind-ignore href="#6-using-tls-in-traefik" aria-label="Link to this section">#</a></h2>
<p>Traefik picks up the certificate from the secret named in the Ingress <code>tls</code> section. The Ingress must be in the same namespace as the secret.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">apiVersion</span><span class="p">:</span><span class="w"> </span><span class="l">networking.k8s.io/v1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l">Ingress</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">metadata</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">example-com-ingress</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">spec</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ingressClassName</span><span class="p">:</span><span class="w"> </span><span class="l">traefik</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">tls</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">hosts</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">example.com</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">secretName</span><span class="p">:</span><span class="w"> </span><span class="l">example-com-tls-secret</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">rules</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">host</span><span class="p">:</span><span class="w"> </span><span class="l">example.com</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">http</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">paths</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- <span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="l">/</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">pathType</span><span class="p">:</span><span class="w"> </span><span class="l">Prefix</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">backend</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">              </span><span class="nt">service</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">my-service</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="nt">port</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                  </span><span class="nt">number</span><span class="p">:</span><span class="w"> </span><span class="m">80</span><span class="w">
</span></span></span></code></pre></div><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<p>Follow the chain: Certificate → Order → Challenge. <code>kubectl describe</code> on each shows where it stops.</p>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Cause / fix</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Helm: <code>additional properties 'type' not allowed</code></td>
					<td>Use <code>service.spec.type</code> with current Traefik charts.</td>
			</tr>
			<tr>
					<td>ACME-DNS pod crashes with <code>configuration file not found</code></td>
					<td>ConfigMap not mounted at <code>/etc/acme-dns</code>.</td>
			</tr>
			<tr>
					<td>Challenge stays pending</td>
					<td>Check <code>dig TXT _acme-challenge.example.com</code>: the CNAME and the <code>auth.example.com</code> delegation must both resolve from the internet.</td>
			</tr>
			<tr>
					<td>ACME-DNS returns NXDOMAIN</td>
					<td>You delegated <code>_acme-challenge</code> with NS instead of a CNAME.</td>
			</tr>
			<tr>
					<td>Issuer cannot find credentials</td>
					<td>The <code>account.json</code> key must be the domain name, and the secret must be in <code>cert-manager</code> for a ClusterIssuer.</td>
			</tr>
	</tbody>
</table>
<h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>API stays internal</strong>: with <code>disable_registration = false</code>, anyone reaching the API can register accounts. Never expose the <code>acme-dns</code> Service.</li>
<li><strong>Scoped credentials</strong>: an ACME-DNS account can only update its own TXT record. A leaked <code>acmedns-secret</code> cannot change your main zone.</li>
<li><strong>Back up the database</strong>: the PVC holds the accounts your CNAMEs depend on.</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-cert-manager-acme-dns" rel="noopener">pderuiter/blog-cert-manager-acme-dns</a>. It creates a single-node k3s cluster with Traefik, cert-manager and ACME-DNS, registers the ACME-DNS accounts, creates the ClusterIssuer, and prints the NS, glue and CNAME records for your main DNS. Run <code>terraform apply</code>, then <code>ansible-playbook site.yml</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>Each part has one job:</p>
<ol>
<li><strong>Traefik</strong> routes traffic and serves the certificates</li>
<li><strong>cert-manager</strong> issues and renews them</li>
<li><strong>ACME-DNS</strong> solves the DNS-01 challenges, with minimal exposure of your main DNS zone</li>
</ol>
<p>Add a domain by registering an ACME-DNS account, adding its CNAME and adding it to the secret.</p>
]]></content:encoded></item><item><title>OpenBSD VPN Road Warrior Setup with IKEv2</title><link>https://blog.bsdserver.nl/openbsd-vpn-road-warrior-setup-with-ikev2/</link><guid isPermaLink="false">693b521479eb54000160a4bb</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Thu, 11 Dec 2025 23:21:56 +0000</pubDate><description>Introduction OpenBSD is known for its security and clean design, making it an ideal choice for a VPN server.</description><category>OpenBSD</category><category>VPN</category><category>Security</category><category>Networking</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/openbsd-road-warior-vpn.png" medium="image"/><content:encoded><![CDATA[<p>Laptops and phones on the road need a secure way back into your network, or a trusted exit to the internet from hotel and café Wi-Fi. OpenBSD is known for its security and clean design, making it an ideal choice for that VPN server.</p>
<p>This guide sets up a road warrior (mobile client) VPN on OpenBSD with iked, the native IKEv2 daemon. The steps were verified on OpenBSD 7.9. Clients authenticate the server by certificate and themselves with a username and password.</p>
<h2 id="why-iked">Why iked? <a class="anchor" data-pagefind-ignore href="#why-iked" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>In base</strong> - iked, PF and LibreSSL ship with OpenBSD. Nothing to install.</li>
<li><strong>IKEv2</strong> - The protocol most desktop and mobile operating systems support natively, so clients often need no extra app.</li>
<li><strong>Small configuration</strong> - One policy in <code>/etc/iked.conf</code> covers all road warriors.</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 a handful to a few dozen mobile users who need access to your network or a trusted exit to the internet.</li>
<li><strong>Skip it</strong> for site-to-site links between fixed networks (a different iked policy) or when you need per-user certificates and central user management; this setup keeps users in a config file.</li>
</ul>
<h2 id="how-it-works">How It Works <a class="anchor" data-pagefind-ignore href="#how-it-works" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>iked</td>
					<td>VPN server</td>
					<td>Negotiates IKEv2, authenticates clients (EAP-MSCHAPv2), hands out addresses and DNS.</td>
			</tr>
			<tr>
					<td>Certificates (CA + server)</td>
					<td>VPN server, CA cert also on clients</td>
					<td>Prove to clients that they talk to the real server.</td>
			</tr>
			<tr>
					<td>PF</td>
					<td>VPN server</td>
					<td>Lets IKE and ESP in, passes tunnel traffic on <code>enc0</code>, NATs clients to the internet.</td>
			</tr>
			<tr>
					<td>IKEv2 client</td>
					<td>Laptop or phone</td>
					<td>Connects, checks the server certificate, logs in with username and password.</td>
			</tr>
	</tbody>
</table>
<p>The flow: client connects on UDP 500/4500 → verifies the server certificate against the CA → logs in with EAP → gets an address from <code>10.10.10.0/24</code> → its traffic goes through the tunnel → PF NATs it out of the server.</p>
<h2 id="prerequisites">Prerequisites <a class="anchor" data-pagefind-ignore href="#prerequisites" aria-label="Link to this section">#</a></h2>
<ul>
<li>A VPS or dedicated server running a supported OpenBSD release (the steps were verified on 7.9)</li>
<li>A domain name or static public IP address for the VPN server</li>
<li>Root access to your server</li>
</ul>
<h2 id="step-1-generate-certificates-and-keys">Step 1: Generate Certificates and Keys <a class="anchor" data-pagefind-ignore href="#step-1-generate-certificates-and-keys" aria-label="Link to this section">#</a></h2>
<p>Clients must be sure they talk to your server before they send a password. You build a small CA with OpenSSL (LibreSSL) and use it to sign the server certificate.</p>
<h3 id="create-the-directory-for-private-keys">Create the Directory for Private Keys <a class="anchor" data-pagefind-ignore href="#create-the-directory-for-private-keys" aria-label="Link to this section">#</a></h3>
<p>On OpenBSD <code>/etc/ssl/private</code> already exists, so <code>-p</code> keeps <code>mkdir</code> from failing; <code>chmod 700</code> keeps it root-only:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl"><span class="nb">cd</span> /etc/ssl
</span></span><span class="line"><span class="cl">mkdir -p private
</span></span><span class="line"><span class="cl">chmod <span class="m">700</span> private
</span></span></code></pre></div><h3 id="generate-the-ca-private-key">Generate the CA Private Key <a class="anchor" data-pagefind-ignore href="#generate-the-ca-private-key" aria-label="Link to this section">#</a></h3>
<p>This key signs the server&rsquo;s certificate. Anyone who has it can create certificates your clients trust, so keep it protected:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl">openssl genrsa -out private/cakey.pem <span class="m">4096</span>
</span></span></code></pre></div><h3 id="create-the-ca-certificate">Create the CA Certificate <a class="anchor" data-pagefind-ignore href="#create-the-ca-certificate" aria-label="Link to this section">#</a></h3>
<p>This self-signed certificate is what clients trust. OpenBSD&rsquo;s LibreSSL <code>openssl.cnf</code> adds no extensions by default, so without the <code>-addext</code> lines you get an X.509 v1 certificate without the CA flag, which clients such as strongSwan reject (&ldquo;ca certificate lacks CA basic constraint&rdquo;):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl">openssl req -x509 -new -nodes <span class="se">\
</span></span></span><span class="line"><span class="cl">            -key private/cakey.pem <span class="se">\
</span></span></span><span class="line"><span class="cl">            -sha256 -days <span class="m">3650</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">            -out cacert.pem <span class="se">\
</span></span></span><span class="line"><span class="cl">            -subj <span class="s2">&#34;/C=NL/O=VPN/CN=VPN CA&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">            -addext <span class="s2">&#34;basicConstraints=critical,CA:TRUE&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">            -addext <span class="s2">&#34;keyUsage=critical,keyCertSign,cRLSign&#34;</span>
</span></span></code></pre></div><h3 id="generate-the-vpn-server-key">Generate the VPN Server Key <a class="anchor" data-pagefind-ignore href="#generate-the-vpn-server-key" aria-label="Link to this section">#</a></h3>
<p>The server&rsquo;s own private key:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl">openssl genrsa -out private/vpn-server-key.pem <span class="m">4096</span>
</span></span></code></pre></div><h3 id="create-the-vpn-server-certificate-signing-request-csr">Create the VPN Server Certificate Signing Request (CSR) <a class="anchor" data-pagefind-ignore href="#create-the-vpn-server-certificate-signing-request-csr" aria-label="Link to this section">#</a></h3>
<p>The CSR carries the server&rsquo;s name and public key to the CA for signing:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl">openssl req -new -key private/vpn-server-key.pem <span class="se">\
</span></span></span><span class="line"><span class="cl">            -out vpn-server-csr.pem <span class="se">\
</span></span></span><span class="line"><span class="cl">            -subj <span class="s2">&#34;/C=NL/O=VPN/CN=vpn.example.com&#34;</span>
</span></span></code></pre></div><h3 id="sign-the-vpn-server-certificate">Sign the VPN Server Certificate <a class="anchor" data-pagefind-ignore href="#sign-the-vpn-server-certificate" aria-label="Link to this section">#</a></h3>
<p>The CA signs the CSR. Two extensions matter:</p>
<ul>
<li><code>subjectAltName=DNS:vpn.example.com</code>: the name clients connect to. It must match.</li>
<li><code>extendedKeyUsage=serverAuth</code>: expected by Windows and Apple clients.</li>
</ul>
<p>OpenBSD&rsquo;s default shell (ksh) does not support <code>&lt;(...)</code> process substitution, so write the extensions to a file first:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl"><span class="nb">printf</span> <span class="s2">&#34;subjectAltName=DNS:vpn.example.com\nextendedKeyUsage=serverAuth\n&#34;</span> &gt; vpn-server-ext.cnf
</span></span><span class="line"><span class="cl">openssl x509 -req -in vpn-server-csr.pem <span class="se">\
</span></span></span><span class="line"><span class="cl">             -CA cacert.pem -CAkey private/cakey.pem <span class="se">\
</span></span></span><span class="line"><span class="cl">             -CAcreateserial -out vpn-server-cert.pem <span class="se">\
</span></span></span><span class="line"><span class="cl">             -days <span class="m">1825</span> -sha256 <span class="se">\
</span></span></span><span class="line"><span class="cl">             -extfile vpn-server-ext.cnf
</span></span></code></pre></div><h3 id="install-the-certificates-for-iked">Install the Certificates for iked <a class="anchor" data-pagefind-ignore href="#install-the-certificates-for-iked" aria-label="Link to this section">#</a></h3>
<p>iked does not look in <code>/etc/ssl</code>. It loads its files from its own directories:</p>
<table>
	<thead>
			<tr>
					<th>File</th>
					<th>Location</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>CA certificates</td>
					<td><code>/etc/iked/ca/</code></td>
			</tr>
			<tr>
					<td>Its own certificate</td>
					<td><code>/etc/iked/certs/</code></td>
			</tr>
			<tr>
					<td>Its private key</td>
					<td><code>/etc/iked/private/local.key</code></td>
			</tr>
	</tbody>
</table>
<p>Skip this step and iked silently authenticates with the raw public key it generated at install time; clients then fail with &ldquo;no trusted ECDSA public key found for &lsquo;vpn.example.com&rsquo;&rdquo;. The first command keeps a backup of that generated key:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl">cp /etc/iked/private/local.key /etc/iked/private/local.key.orig
</span></span><span class="line"><span class="cl">cp /etc/ssl/cacert.pem /etc/iked/ca/ca.crt
</span></span><span class="line"><span class="cl">cp /etc/ssl/vpn-server-cert.pem /etc/iked/certs/vpn.example.com.crt
</span></span><span class="line"><span class="cl">install -m <span class="m">600</span> /etc/ssl/private/vpn-server-key.pem /etc/iked/private/local.key
</span></span></code></pre></div><p>Copy <code>cacert.pem</code> (never the key) to your clients so they can verify the server.</p>
<h2 id="step-2-edit-iked-configuration">Step 2: Edit iked Configuration <a class="anchor" data-pagefind-ignore href="#step-2-edit-iked-configuration" aria-label="Link to this section">#</a></h2>
<p><code>/etc/iked.conf</code> holds the users and one policy that accepts all road warrior clients. Open it with your preferred editor (vi is in base; vim is a package):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl">vi /etc/iked.conf
</span></span></code></pre></div><p>And add the following configuration:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl">user <span class="s2">&#34;username&#34;</span> <span class="s2">&#34;password&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">ikev2 <span class="s2">&#34;roadwarrior&#34;</span> passive esp <span class="se">\
</span></span></span><span class="line"><span class="cl">    from 0.0.0.0/0 to dynamic <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="nb">local</span> 82.197.198.151 peer any <span class="se">\
</span></span></span><span class="line"><span class="cl">    srcid vpn.example.com <span class="se">\
</span></span></span><span class="line"><span class="cl">    eap <span class="s2">&#34;mschap-v2&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    config address 10.10.10.0/24 <span class="se">\
</span></span></span><span class="line"><span class="cl">    config name-server 192.168.2.166 <span class="se">\
</span></span></span><span class="line"><span class="cl">    tag <span class="s2">&#34;</span><span class="nv">$name</span><span class="s2">&#34;</span>
</span></span></code></pre></div><table>
	<thead>
			<tr>
					<th>Setting</th>
					<th>What it does</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>user &quot;username&quot; &quot;password&quot;</code></td>
					<td>A client login. Add one <code>user</code> line per client.</td>
			</tr>
			<tr>
					<td><code>passive</code></td>
					<td>The server waits for clients to connect; it never initiates.</td>
			</tr>
			<tr>
					<td><code>from 0.0.0.0/0 to dynamic</code></td>
					<td>Clients reach everything through the tunnel; <code>dynamic</code> narrows the flow to the address each client is assigned.</td>
			</tr>
			<tr>
					<td><code>local 82.197.198.151 peer any</code></td>
					<td>Replace with your VPN server&rsquo;s public IP. <code>peer any</code>: clients connect from any address.</td>
			</tr>
			<tr>
					<td><code>srcid vpn.example.com</code></td>
					<td>The server&rsquo;s identity. Must match the certificate name.</td>
			</tr>
			<tr>
					<td><code>eap &quot;mschap-v2&quot;</code></td>
					<td>Clients authenticate with a <code>user</code> name and password.</td>
			</tr>
			<tr>
					<td><code>config address 10.10.10.0/24</code></td>
					<td>The pool client addresses come from.</td>
			</tr>
			<tr>
					<td><code>config name-server 192.168.2.166</code></td>
					<td>The DNS server pushed to clients. Set your own.</td>
			</tr>
			<tr>
					<td><code>tag &quot;$name&quot;</code></td>
					<td>Tags the tunnel&rsquo;s traffic for PF. The rules below do not need it.</td>
			</tr>
	</tbody>
</table>
<p>Do not use <code>to 0.0.0.0/0</code> instead of <code>to dynamic</code>: that installs a 0.0.0.0/0 -&gt; 0.0.0.0/0 flow on the server and sends all of the server&rsquo;s own traffic (including your SSH session) into the first client&rsquo;s tunnel.</p>
<p>Make sure the file is only readable by root, or iked refuses to load it. <code>iked -n</code> checks the syntax without starting anything:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl">chmod <span class="m">600</span> /etc/iked.conf
</span></span><span class="line"><span class="cl">iked -n
</span></span></code></pre></div><h2 id="step-3-configure-pf-firewall-rules">Step 3: Configure PF Firewall Rules <a class="anchor" data-pagefind-ignore href="#step-3-configure-pf-firewall-rules" aria-label="Link to this section">#</a></h2>
<p>PF must let the VPN protocols in and NAT the clients out. Open the PF configuration file:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl">vi /etc/pf.conf
</span></span></code></pre></div><p>Add the following rules to permit IKE and ESP traffic and to NAT the VPN clients out of the server:</p>
<pre tabindex="0"><code>pass in quick on egress proto udp from any to any port { 500, 4500 }
pass out quick on egress proto udp from any to any port { 500, 4500 }
pass in quick on egress proto esp from any to any
pass out quick on egress proto esp from any to any
pass in quick on enc0 all
pass out quick on enc0 all
match out on egress from 10.10.10.0/24 to any nat-to (egress:0)
</code></pre><table>
	<thead>
			<tr>
					<th>Rule</th>
					<th>Why</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>UDP 500, 4500</td>
					<td>IKE, and NAT traversal for clients behind NAT (most of them).</td>
			</tr>
			<tr>
					<td><code>proto esp</code></td>
					<td>Encrypted traffic from clients that are not behind NAT.</td>
			</tr>
			<tr>
					<td><code>enc0</code></td>
					<td>The decrypted tunnel traffic appears on this interface.</td>
			</tr>
			<tr>
					<td><code>nat-to (egress:0)</code></td>
					<td>Client traffic leaves with the server&rsquo;s public address.</td>
			</tr>
	</tbody>
</table>
<p>The server must also forward packets between the tunnel and the internet. The first command enables it now, the second after a reboot:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl">sysctl net.inet.ip.forwarding<span class="o">=</span><span class="m">1</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s1">&#39;net.inet.ip.forwarding=1&#39;</span> &gt;&gt; /etc/sysctl.conf
</span></span></code></pre></div><p>Reload the PF configuration:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl">pfctl -f /etc/pf.conf
</span></span></code></pre></div><h2 id="step-4-enable-and-start-the-iked-service">Step 4: Enable and Start the iked Service <a class="anchor" data-pagefind-ignore href="#step-4-enable-and-start-the-iked-service" aria-label="Link to this section">#</a></h2>
<p>Enable the service so iked starts at boot. No flags are needed: iked no longer blocks the server&rsquo;s own IPv6 traffic, and on 7.9 the old <code>-6</code> flag only logs &ldquo;the -6 option is ignored and will be removed in the future&rdquo;:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl">rcctl <span class="nb">enable</span> iked
</span></span></code></pre></div><p>Start the service:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-shell" data-lang="shell"><span class="line"><span class="cl">rcctl start iked
</span></span></code></pre></div><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Cause / fix</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Client: &ldquo;no trusted ECDSA public key found for &lsquo;vpn.example.com&rsquo;&rdquo;</td>
					<td>iked uses its raw install-time key. Install the certificates in <code>/etc/iked/</code> (Step 1).</td>
			</tr>
			<tr>
					<td>strongSwan: &ldquo;ca certificate lacks CA basic constraint&rdquo;</td>
					<td>CA created without the <code>-addext</code> lines. Recreate it.</td>
			</tr>
			<tr>
					<td>iked refuses to load the config</td>
					<td><code>/etc/iked.conf</code> is not mode 600.</td>
			</tr>
			<tr>
					<td>SSH to the server drops when a client connects</td>
					<td>The policy uses <code>to 0.0.0.0/0</code>. Use <code>to dynamic</code>.</td>
			</tr>
			<tr>
					<td>Clients connect but cannot reach the internet</td>
					<td>IP forwarding off, or the <code>nat-to</code> rule missing.</td>
			</tr>
	</tbody>
</table>
<h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Passwords are in plain text</strong> in <code>/etc/iked.conf</code>. Keep it mode 600 and use a unique password per client.</li>
<li><strong>Protect the CA key.</strong> <code>/etc/ssl/private/cakey.pem</code> can sign certificates your clients trust. Consider moving it off the server once the certificate is signed.</li>
<li><strong>Clients must verify the server.</strong> Install <code>cacert.pem</code> on every client; EAP passwords are only safe when the server is authenticated first.</li>
</ul>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>OpenBSD is now an IKEv2 VPN server with base tools only: iked for the tunnels, PF for filtering and NAT. Road warrior clients connect from anywhere with encrypted traffic, and adding a user is one line in <code>iked.conf</code>.</p>
]]></content:encoded></item><item><title>Setting Up TACACS+ on OpenBSD 7.9 for Legacy Network Devices</title><link>https://blog.bsdserver.nl/setting-up-tacacs-on-openbsd-7-4-for-legacy-network-devices/</link><guid isPermaLink="false">693b516f79eb54000160a499</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Thu, 11 Dec 2025 23:19:11 +0000</pubDate><description>TACACS+ (Terminal Access Controller Access-Control System Plus) is a protocol that provides authentication, authorization, and accounting (AAA) services.</description><category>OpenBSD</category><category>TACACS+</category><category>Security</category><category>Networking</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/openbsd-tacacs.png" medium="image"/><content:encoded><![CDATA[<p>TACACS+ (Terminal Access Controller Access-Control System Plus) is a protocol that provides authentication, authorization, and accounting (AAA) services. It is commonly used to control access to network devices from one central place, instead of a local account on every switch.</p>
<p>This post installs the tac_plus TACACS+ server on OpenBSD, restricted to a management network. OpenBSD&rsquo;s security-oriented approach gives a stable environment for a protocol that itself is weak.</p>
<p><strong>Critical Security Warning:</strong> TACACS+ is <strong>horribly insecure</strong> and should only be used when no better alternatives, such as <strong>RADIUS with RadSec</strong>, are available. It transmits authentication information in a way that is susceptible to interception, making it unsuitable for modern secure environments. Additionally, the simplest tac_plus configuration (<code>global = cleartext</code>, used below) <strong>stores passwords in clear text</strong>, which poses a significant security risk. tac_plus can store bcrypt hashes instead (<code>login = des</code> and <code>pap = des</code>, hashes generated with <code>encrypt(1)</code>), but the <code>global</code> keyword only accepts cleartext.</p>
<p><strong>TACACS+ should only be used in a network segment that has no direct internet access and in a VLAN that is exclusively dedicated to management purposes.</strong> It should only be deployed when there is <strong>no other way</strong> to centrally manage devices.</p>
<h2 id="why-tacacs">Why TACACS+? <a class="anchor" data-pagefind-ignore href="#why-tacacs" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Central logins</strong> - One user list for all devices, instead of local accounts per switch.</li>
<li><strong>Accounting</strong> - A log of who did what on which device.</li>
<li><strong>Legacy support</strong> - Old devices that only speak TACACS+, or handle RADIUS badly.</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> only for legacy devices without a better option. I use TACACS+ for authenticating to some old Zyxel switches that do not work well with RADIUS, a necessary compromise in specific legacy environments.</li>
<li><strong>Skip it</strong> for anything that supports RADIUS with RadSec or another modern mechanism.</li>
</ul>
<h2 id="how-it-works">How It Works <a class="anchor" data-pagefind-ignore href="#how-it-works" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>tac_plus</td>
					<td>OpenBSD server, management VLAN</td>
					<td>Checks logins against <code>/etc/tac_plus.conf</code>, writes accounting records.</td>
			</tr>
			<tr>
					<td>TACACS+ client</td>
					<td>Each network device</td>
					<td>Sends login attempts to tac_plus on TCP port 49, using the shared key.</td>
			</tr>
			<tr>
					<td>newsyslog</td>
					<td>OpenBSD server</td>
					<td>Rotates the tac_plus log files.</td>
			</tr>
	</tbody>
</table>
<p>The flow: an admin logs in on a switch → the switch sends the credentials to tac_plus on port 49 → tac_plus checks the user → accept or reject → the session is logged to the accounting file and syslog.</p>
<h2 id="step-1-install-tacacs-on-openbsd">Step 1: Install TACACS+ on OpenBSD <a class="anchor" data-pagefind-ignore href="#step-1-install-tacacs-on-openbsd" aria-label="Link to this section">#</a></h2>
<p>The server is a package from the OpenBSD ports tree:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">pkg_add tacacs+
</span></span></code></pre></div><p>This installs tac_plus F4.0.4.28 (package <code>tacacs+-4.0.4.28p4v0</code>, with Python 3 as a dependency), creates the <code>_tacacs</code> user and group, and installs <code>/etc/rc.d/tac_plus</code> plus a sample <code>/etc/tac_plus.conf</code>. These steps were verified on OpenBSD 7.9.</p>
<h2 id="step-2-configure-log-rotation">Step 2: Configure Log Rotation <a class="anchor" data-pagefind-ignore href="#step-2-configure-log-rotation" aria-label="Link to this section">#</a></h2>
<p>Accounting logs grow with every login and command. Add the following entries to <code>/etc/newsyslog.conf</code> so they are rotated:</p>
<pre tabindex="0"><code>/var/log/tac_plus/tac.acct        _tacacs:_tacacs 644  7     250  *     Z
/var/log/tac_plus/tac.log         _tacacs:_tacacs 644  7     250  *     Z
/var/log/tac_plus/tacwho.log      _tacacs:_tacacs 644  7     250  *     Z
</code></pre><ul>
<li><code>_tacacs:_tacacs 644</code>: owner and mode of the new log file, so tac_plus can keep writing.</li>
<li><code>7</code>: number of old files to keep.</li>
<li><code>250</code>: rotate when the file reaches 250 KB.</li>
<li><code>*</code>: no time-based rotation; size only.</li>
<li><code>Z</code>: compress rotated files.</li>
</ul>
<p>newsyslog runs from cron and rereads <code>/etc/newsyslog.conf</code> on every run, so nothing needs to be restarted. Check the entries with a dry run:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">newsyslog -n -v <span class="p">|</span> grep tac_plus
</span></span></code></pre></div><p>newsyslog skips files that do not exist yet, so on a fresh install this prints nothing. After the first login <code>tac.acct</code> shows up (<code>/var/log/tac_plus/tac.acct &lt;7Z&gt;: size (KB): ...</code>); a malformed line is reported as an error instead.</p>
<p>Note that tac_plus only writes <code>tac.log</code> when started with <code>-d</code>; its normal messages go to syslog (<code>/var/log/daemon</code>).</p>
<h2 id="step-3-configure-tacacs">Step 3: Configure TACACS+ <a class="anchor" data-pagefind-ignore href="#step-3-configure-tacacs" aria-label="Link to this section">#</a></h2>
<p><code>/etc/tac_plus.conf</code> holds the shared key, where accounting goes, and the users. Replace the sample with:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl"><span class="nv">key</span> <span class="o">=</span> <span class="s2">&#34;your_shared_secret_here&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Default accounting file</span>
</span></span><span class="line"><span class="cl">accounting <span class="nv">file</span> <span class="o">=</span> /var/log/tac_plus/tac.acct
</span></span><span class="line"><span class="cl">accounting syslog
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># User definition</span>
</span></span><span class="line"><span class="cl"><span class="nv">user</span> <span class="o">=</span> administrator <span class="o">{</span>
</span></span><span class="line"><span class="cl">  default <span class="nv">service</span> <span class="o">=</span> permit
</span></span><span class="line"><span class="cl">  <span class="nv">global</span> <span class="o">=</span> cleartext your_password_here
</span></span><span class="line"><span class="cl">  <span class="nv">service</span> <span class="o">=</span> <span class="nb">exec</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">    priv-lvl <span class="o">=</span> <span class="m">15</span>
</span></span><span class="line"><span class="cl">  <span class="o">}</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span></code></pre></div><table>
	<thead>
			<tr>
					<th>Setting</th>
					<th>What it does</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>key</code></td>
					<td>Shared secret between tac_plus and the devices. Configure the same value on each switch.</td>
			</tr>
			<tr>
					<td><code>accounting file</code></td>
					<td>Where accounting records are written (rotated in Step 2).</td>
			</tr>
			<tr>
					<td><code>accounting syslog</code></td>
					<td>Also send accounting records to syslog.</td>
			</tr>
			<tr>
					<td><code>user = ... { global = cleartext ... }</code></td>
					<td>A login and its password, for all services. Use <code>login = des</code> / <code>pap = des</code> with a hash to avoid cleartext.</td>
			</tr>
			<tr>
					<td><code>default service = permit</code></td>
					<td>Authorizes every service and command for this user. Must be the first line in the block.</td>
			</tr>
			<tr>
					<td><code>service = exec { priv-lvl = 15 }</code></td>
					<td>Gives the user privilege level 15 (full admin) on a device that asks for exec authorization.</td>
			</tr>
	</tbody>
</table>
<p>tac_plus denies authorization for anything that is not explicitly permitted. Without the last two settings the password check passes, but a switch that also asks for authorization refuses the shell.</p>
<p>Change the shared secret and user password to secure values. <code>-P</code> only parses the file and prints it, so you can check it before starting:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">tac_plus -C /etc/tac_plus.conf -P
</span></span></code></pre></div><h2 id="step-4-enable-tacacs-and-configure-the-listening-interface">Step 4: Enable TACACS+ and Configure the Listening Interface <a class="anchor" data-pagefind-ignore href="#step-4-enable-tacacs-and-configure-the-listening-interface" aria-label="Link to this section">#</a></h2>
<p>By default tac_plus listens on all addresses. <code>-B</code> binds it to the management address only.</p>
<p>Don&rsquo;t edit <code>/etc/rc.d/tac_plus</code> itself (package updates overwrite it and <code>pkg_check</code> flags it as modified); use <code>rcctl</code>, which stores the flags in <code>/etc/rc.conf.local</code>. Enable the service first: for a package service <code>rcctl set</code> refuses with &ldquo;rcctl: tac_plus is not enabled&rdquo;.</p>
<p>The flags replace the script&rsquo;s defaults, so repeat <code>-C</code>, <code>-Q</code> and <code>-U</code>; without <code>-C</code> tac_plus exits with &ldquo;no config file specified&rdquo;:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">rcctl <span class="nb">enable</span> tac_plus
</span></span><span class="line"><span class="cl">rcctl <span class="nb">set</span> tac_plus flags -C /etc/tac_plus.conf -Q _tacacs -U _tacacs -B 192.168.2.254
</span></span></code></pre></div><table>
	<thead>
			<tr>
					<th>Flag</th>
					<th>What it does</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>-C /etc/tac_plus.conf</code></td>
					<td>The configuration file. Required.</td>
			</tr>
			<tr>
					<td><code>-Q _tacacs</code> / <code>-U _tacacs</code></td>
					<td>Group and user tac_plus runs as, instead of root.</td>
			</tr>
			<tr>
					<td><code>-B 192.168.2.254</code></td>
					<td>The address to listen on. Use your management address.</td>
			</tr>
	</tbody>
</table>
<h2 id="step-5-start-tacacs">Step 5: Start TACACS+ <a class="anchor" data-pagefind-ignore href="#step-5-start-tacacs" aria-label="Link to this section">#</a></h2>
<p>The service now starts at boot; start it now as well:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">rcctl start tac_plus
</span></span></code></pre></div><p>Verify the service:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">rcctl check tac_plus
</span></span><span class="line"><span class="cl">netstat -an -f inet -p tcp <span class="p">|</span> grep <span class="s1">&#39;\.49 &#39;</span>
</span></span></code></pre></div><p>The listener should show your management address (for example <code>192.168.2.254.49</code>), not <code>*.49</code>.</p>
<h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Cause / fix</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>rcctl: tac_plus is not enabled</code></td>
					<td>Run <code>rcctl enable tac_plus</code> before <code>rcctl set</code>.</td>
			</tr>
			<tr>
					<td>tac_plus exits with &ldquo;no config file specified&rdquo;</td>
					<td>The <code>rcctl</code> flags lack <code>-C /etc/tac_plus.conf</code>.</td>
			</tr>
			<tr>
					<td>tac_plus exits with &ldquo;Unrecognised keyword default for user&rdquo;</td>
					<td><code>default service</code> is not the first line in the <code>user</code> block.</td>
			</tr>
			<tr>
					<td>Login accepted, but the switch refuses the shell</td>
					<td>The device asks for authorization; add <code>default service = permit</code> and <code>service = exec</code>.</td>
			</tr>
			<tr>
					<td>Listener shows <code>*.49</code></td>
					<td><code>-B</code> is not in the flags. Check <code>rcctl get tac_plus flags</code>.</td>
			</tr>
			<tr>
					<td><code>tac.log</code> stays empty</td>
					<td>Normal: without <code>-d</code> messages go to <code>/var/log/daemon</code>.</td>
			</tr>
	</tbody>
</table>
<h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Restrict access</strong>: Use firewall rules to allow only trusted devices to reach port 49.</li>
<li><strong>Use encryption</strong>: Implement encrypted communication channels where possible.</li>
<li><strong>Rotate credentials</strong>: Regularly update shared secrets and user passwords.</li>
<li><strong>Monitor logs</strong>: Periodically review logs for suspicious activities.</li>
</ul>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>You now have a TACACS+ server on OpenBSD, listening only on the management network. However, <strong>TACACS+ is fundamentally insecure</strong> and should only be used when no better alternatives are available.</p>
<p><strong>Key Takeaways:</strong></p>
<ul>
<li>TACACS+ is commonly configured with clear-text passwords (as in this guide), making it <strong>extremely insecure</strong>.</li>
<li>It should <strong>only</strong> be deployed in a <strong>segmented network</strong> with no direct internet access.</li>
<li>It should only be used when no other option exists for centrally managing legacy devices.</li>
</ul>
<p><strong>If possible, consider migrating to a more secure authentication mechanism to better protect your network environment.</strong></p>
]]></content:encoded></item><item><title>Securing HAProxy with Coraza-SPOA: A Step-by-Step Guide</title><link>https://blog.bsdserver.nl/securing-haproxy-with-coraza-spoa-a-step-by-step-guide/</link><guid isPermaLink="false">693b50e879eb54000160a470</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Thu, 11 Dec 2025 23:16:56 +0000</pubDate><description>Coraza-SPOA offers a powerful way to add Web Application Firewall (WAF) capabilities to HAProxy, enhancing security for your web applications.</description><category>HAProxy</category><category>Security</category><category>WAF</category><category>Coraza</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/haproxy-coraza-waf.png" medium="image"/><content:encoded><![CDATA[<p>Coraza-SPOA offers a powerful way to add Web Application Firewall (WAF) capabilities to HAProxy. HAProxy routes and balances requests but does not look for SQL injection, XSS or path traversal in them; a WAF does.</p>
<p>This guide compiles Coraza-SPOA, loads the OWASP Core Rule Set, runs it as a systemd service, and connects HAProxy to it so that malicious requests get a 403 before they reach your application.</p>
<h2 id="why-coraza-spoa">Why Coraza-SPOA? <a class="anchor" data-pagefind-ignore href="#why-coraza-spoa" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>OWASP Core Rule Set</strong>: a maintained, widely used rule set against common web attacks</li>
<li><strong>ModSecurity-compatible rules</strong>: Coraza reads the SecLang rule language</li>
<li><strong>Separate process</strong>: the WAF runs outside HAProxy; HAProxy only asks for a verdict</li>
<li><strong>Open source</strong>: no commercial HAProxy edition needed</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> in front of web applications you cannot fully trust or patch quickly: CMSs, legacy apps, third-party software.</li>
<li><strong>Skip it</strong> for pure APIs with strict input validation, or traffic that is not HTTP. Every request takes an extra round trip to the agent, and the CRS needs tuning against false positives.</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>Receives requests; the SPOE filter sends each one to the agent and acts on the verdict.</td>
			</tr>
			<tr>
					<td>Coraza-SPOA</td>
					<td>Same host, <code>127.0.0.1:9000</code></td>
					<td>Evaluates the request against the rules and returns an action.</td>
			</tr>
			<tr>
					<td>Core Rule Set</td>
					<td><code>/etc/coraza-spoa/rules/</code></td>
					<td>The attack-detection rules Coraza loads.</td>
			</tr>
			<tr>
					<td>Backend</td>
					<td>App servers</td>
					<td>Only receives requests Coraza allowed. Here: a static test response.</td>
			</tr>
	</tbody>
</table>
<p>The flow: request arrives → SPOE sends method, path, headers and body to Coraza-SPOA → Coraza runs the rules → HAProxy reads <code>txn.coraza.action</code> → <code>deny</code> gives a 403, otherwise the request goes to the backend.</p>
<h2 id="step-1-clone-and-compile-coraza-spoa">Step 1: Clone and Compile Coraza-SPOA <a class="anchor" data-pagefind-ignore href="#step-1-clone-and-compile-coraza-spoa" aria-label="Link to this section">#</a></h2>
<p>There are no packages, so you build the binary from source. Make sure you have Go installed before proceeding. The project builds with <a href="https://magefile.org/" rel="noopener">Mage</a> through <code>go run</code>, so nothing else needs to be installed.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl"><span class="c1"># Clone the Coraza-SPOA repo</span>
</span></span><span class="line"><span class="cl">git clone https://github.com/corazawaf/coraza-spoa.git
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Change into the directory and compile the binary (needs Go 1.25+;</span>
</span></span><span class="line"><span class="cl"><span class="c1"># the result is build/coraza-spoa)</span>
</span></span><span class="line"><span class="cl"><span class="nb">cd</span> coraza-spoa
</span></span><span class="line"><span class="cl">go run mage.go build
</span></span></code></pre></div><h2 id="step-2-install-the-binary-and-set-permissions">Step 2: Install the Binary and Set Permissions <a class="anchor" data-pagefind-ignore href="#step-2-install-the-binary-and-set-permissions" aria-label="Link to this section">#</a></h2>
<p>Copy the binary to the path the bundled systemd unit expects, owned by root so the service user cannot replace it.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl"><span class="c1"># Place the binary in /usr/bin (the path contrib/coraza-spoa.service starts;</span>
</span></span><span class="line"><span class="cl"><span class="c1"># that unit also makes /usr/local inaccessible)</span>
</span></span><span class="line"><span class="cl">cp -p build/coraza-spoa /usr/bin/coraza-spoa
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Set ownership and permissions</span>
</span></span><span class="line"><span class="cl">chown root:root /usr/bin/coraza-spoa
</span></span><span class="line"><span class="cl">chmod <span class="m">755</span> /usr/bin/coraza-spoa
</span></span></code></pre></div><h2 id="step-3-create-directory-structure-for-logs-and-configuration">Step 3: Create Directory Structure for Logs and Configuration <a class="anchor" data-pagefind-ignore href="#step-3-create-directory-structure-for-logs-and-configuration" aria-label="Link to this section">#</a></h2>
<p>Coraza-SPOA reads its configuration from <code>/etc/coraza-spoa</code> and writes logs to <code>/var/log/coraza-spoa</code>.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl"><span class="c1"># Create directories</span>
</span></span><span class="line"><span class="cl">mkdir -p /etc/coraza-spoa
</span></span><span class="line"><span class="cl">mkdir -p /var/log/coraza-spoa/audit
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create necessary log files</span>
</span></span><span class="line"><span class="cl">touch /var/log/coraza-spoa/server.log
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Repeat for all required log files</span>
</span></span><span class="line"><span class="cl"><span class="k">for</span> logfile in error.log debug.log audit/audit.log<span class="p">;</span> <span class="k">do</span>
</span></span><span class="line"><span class="cl">    touch /var/log/coraza-spoa/<span class="nv">$logfile</span>
</span></span><span class="line"><span class="cl"><span class="k">done</span>
</span></span></code></pre></div><h2 id="step-4-add-user-and-set-permissions">Step 4: Add User and Set Permissions <a class="anchor" data-pagefind-ignore href="#step-4-add-user-and-set-permissions" aria-label="Link to this section">#</a></h2>
<p>For security, Coraza-SPOA runs under its own user: a system account without a home directory or password, so a compromise of the WAF does not give a login.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl"><span class="c1"># Add a system group and user</span>
</span></span><span class="line"><span class="cl">addgroup --quiet --system coraza-spoa
</span></span><span class="line"><span class="cl">adduser --quiet --system --ingroup coraza-spoa --no-create-home --home /nonexistent --disabled-password coraza-spoa
</span></span></code></pre></div><p>There is no need to <code>chown</code> the log directory. The systemd unit from Step 7 has <code>LogsDirectory=coraza-spoa</code>, so every time the service starts, systemd makes <code>/var/log/coraza-spoa</code> and the files in it owned by <code>coraza-spoa:coraza-spoa</code> with mode 0755. A different owner or group set by hand would be undone at the next start.</p>
<h2 id="step-5-configure-coraza-spoa">Step 5: Configure Coraza-SPOA <a class="anchor" data-pagefind-ignore href="#step-5-configure-coraza-spoa" aria-label="Link to this section">#</a></h2>
<p>This file tells the agent where to listen and which rules to load.</p>
<ul>
<li><code>bind: 127.0.0.1:9000</code>: the port HAProxy connects to. Localhost only.</li>
<li><code>applications</code>: a named rule set. HAProxy picks it per request (<code>app=str(haproxy_waf)</code> in Step 9); <code>default_application</code> is used otherwise.</li>
<li><code>directives</code>: the rules, loaded in order: Coraza base settings, CRS setup, CRS plugins, then the CRS rules.</li>
<li><code>response_check: false</code>: only requests are inspected.</li>
<li><code>transaction_ttl_ms</code>: how long the agent keeps a transaction&rsquo;s state.</li>
</ul>
<p>Edit <code>/etc/coraza-spoa/config.yaml</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="c"># Bind address</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">bind</span><span class="p">:</span><span class="w"> </span><span class="m">127.0.0.1</span><span class="p">:</span><span class="m">9000</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">log_level</span><span class="p">:</span><span class="w"> </span><span class="l">info</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">log_file</span><span class="p">:</span><span class="w"> </span><span class="l">/var/log/coraza-spoa/server.log</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">log_format</span><span class="p">:</span><span class="w"> </span><span class="l">console</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">default_application</span><span class="p">:</span><span class="w"> </span><span class="l">haproxy_waf</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">applications</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">haproxy_waf</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">directives</span><span class="p">:</span><span class="w"> </span><span class="p">|</span><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">      Include /etc/coraza-spoa/coraza.conf
</span></span></span><span class="line"><span class="cl"><span class="sd">      Include /etc/coraza-spoa/crs-setup.conf
</span></span></span><span class="line"><span class="cl"><span class="sd">      Include /etc/coraza-spoa/plugins/*-config.conf
</span></span></span><span class="line"><span class="cl"><span class="sd">      Include /etc/coraza-spoa/rules/*.conf</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">response_check</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">transaction_ttl_ms</span><span class="p">:</span><span class="w"> </span><span class="m">60000</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">log_level</span><span class="p">:</span><span class="w"> </span><span class="l">info</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">log_file</span><span class="p">:</span><span class="w"> </span><span class="l">/var/log/coraza-spoa/server.log</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">log_format</span><span class="p">:</span><span class="w"> </span><span class="l">console</span><span class="w">
</span></span></span></code></pre></div><h2 id="step-6-configure-coraza-rules">Step 6: Configure Coraza Rules <a class="anchor" data-pagefind-ignore href="#step-6-configure-coraza-rules" aria-label="Link to this section">#</a></h2>
<p>Create <code>/etc/coraza-spoa/coraza.conf</code> from the Coraza recommended configuration and add the OWASP Core Rule Set.</p>
<table>
	<thead>
			<tr>
					<th>Mode</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>SecRuleEngine DetectionOnly</code></td>
					<td>A new site: log matches, block nothing, tune false positives first</td>
			</tr>
			<tr>
					<td><code>SecRuleEngine On</code></td>
					<td>Blocking mode, once the rules fit your application (the <code>sed</code> below sets this)</td>
			</tr>
	</tbody>
</table>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl"><span class="c1"># Coraza base configuration; switch DetectionOnly to On for blocking mode</span>
</span></span><span class="line"><span class="cl">wget -O /etc/coraza-spoa/coraza.conf <span class="se">\
</span></span></span><span class="line"><span class="cl">  https://raw.githubusercontent.com/corazawaf/coraza/v3.8.1/coraza.conf-recommended
</span></span><span class="line"><span class="cl">sed -i <span class="s1">&#39;s/^SecRuleEngine DetectionOnly/SecRuleEngine On/&#39;</span> /etc/coraza-spoa/coraza.conf
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># OWASP Core Rule Set v4 (the version bundled with current coraza-spoa)</span>
</span></span><span class="line"><span class="cl">git clone --depth <span class="m">1</span> --branch v4.25.0 https://github.com/coreruleset/coreruleset.git
</span></span><span class="line"><span class="cl">cp -p coreruleset/crs-setup.conf.example /etc/coraza-spoa/crs-setup.conf
</span></span><span class="line"><span class="cl">cp -Rp coreruleset/rules /etc/coraza-spoa/
</span></span></code></pre></div><h2 id="step-7-system-configuration">Step 7: System Configuration <a class="anchor" data-pagefind-ignore href="#step-7-system-configuration" aria-label="Link to this section">#</a></h2>
<p>The repository ships a systemd unit and a logrotate file in <code>contrib/</code>. The unit runs the agent as <code>coraza-spoa</code> and creates the log directory; logrotate keeps the logs from filling the disk.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl"><span class="c1"># Copy log rotation configuration and systemd unit files</span>
</span></span><span class="line"><span class="cl">cp -Rp contrib/coraza-spoa.logrotate /etc/logrotate.d/coraza-spoa
</span></span><span class="line"><span class="cl">cp -Rp contrib/coraza-spoa.service /lib/systemd/system/
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Reload systemd and enable the Coraza-SPOA agent</span>
</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> coraza-spoa.service
</span></span><span class="line"><span class="cl">systemctl start coraza-spoa.service
</span></span></code></pre></div><h2 id="step-8-configure-haproxy">Step 8: Configure HAProxy <a class="anchor" data-pagefind-ignore href="#step-8-configure-haproxy" aria-label="Link to this section">#</a></h2>
<p>If HAProxy is not installed yet, install it from the official HAProxy packages rather than the distribution&rsquo;s older <code>haproxy</code> 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"># Official HAProxy packages for Ubuntu 24.04: one PPA per branch</span>
</span></span><span class="line"><span class="cl">sudo add-apt-repository -y ppa:vbernat/haproxy-3.3
</span></span><span class="line"><span class="cl">sudo apt update
</span></span><span class="line"><span class="cl">sudo apt install -y <span class="nv">haproxy</span><span class="o">=</span>3.3.<span class="se">\*</span>
</span></span><span class="line"><span class="cl">haproxy -v
</span></span></code></pre></div><p>3.3 is the newest branch the PPA builds for Ubuntu 24.04, but it is a short-lived stable branch, maintained until about Q1 2027. The newest LTS branch, 3.4, is built for Ubuntu 26.04 (<code>ppa:vbernat/haproxy-3.4</code>) and for Debian 13 on <a href="https://haproxy.debian.net/" rel="noopener">haproxy.debian.net</a>, which lists the repository lines per release and branch. For a long-lived Ubuntu 24.04 install, use the 3.2 LTS branch instead (<code>ppa:vbernat/haproxy-3.2</code>, maintained until 2030).</p>
<p>HAProxy configuration consists of three main steps:</p>
<ol>
<li>Create the frontend.</li>
<li>Create backends for Coraza-SPOA and static content.</li>
<li>Configure the SPOE engine.</li>
</ol>
<p>What the frontend does:</p>
<ul>
<li><code>filter spoe engine coraza</code>: sends every request to the agent, using the SPOE file from Step 9.</li>
<li>First <code>deny</code>: Coraza&rsquo;s verdict is <code>deny</code> → 403.</li>
<li>Second <code>deny</code>: the agent could not be reached or timed out → 500. The WAF fails closed: no verdict, no access.</li>
<li><code>backend coraza-spoa</code>: the agent itself, in <code>mode tcp</code> because SPOP is not HTTP.</li>
</ul>
<p>Add the following frontend and backend configurations in <code>/etc/haproxy/haproxy.cfg</code>:</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend static_test
    mode http
    bind *:80
    filter spoe engine coraza config /etc/haproxy/coraza.cfg
    # Act on the verdict Coraza returns in txn.coraza.action
    http-request deny deny_status 403 if { var(txn.coraza.action) -m str deny }
    http-request deny deny_status 500 if { var(txn.coraza.error) -m int gt 0 }
    use_backend bsdserver_static

backend bsdserver_static
    mode http
    http-request return status 200 content-type &#34;text/plain&#34; string &#34;Welcome!\n&#34;

backend coraza-spoa
    mode tcp
    balance roundrobin
    server s1 127.0.0.1:9000
</code></pre><h2 id="step-9-spoe-configuration-for-haproxy">Step 9: SPOE Configuration for HAProxy <a class="anchor" data-pagefind-ignore href="#step-9-spoe-configuration-for-haproxy" aria-label="Link to this section">#</a></h2>
<p>SPOE (Stream Processing Offload Engine) is how HAProxy hands request data to an external agent. This file says what to send and where the answer goes.</p>
<ul>
<li><code>option var-prefix coraza</code>: the agent&rsquo;s answers become <code>txn.coraza.*</code> variables, such as <code>txn.coraza.action</code>.</li>
<li><code>option set-on-error error</code>: sets <code>txn.coraza.error</code> when the agent fails, which the frontend turns into a 500.</li>
<li><code>timeout processing 500ms</code>: how long HAProxy waits for a verdict.</li>
<li><code>args</code>: the request parts Coraza inspects, including headers and body.</li>
<li><code>event on-frontend-http-request</code>: send the message for every request in the frontend.</li>
</ul>
<p>Edit <code>/etc/haproxy/coraza.cfg</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-cfg" data-lang="cfg"><span class="line"><span class="cl"><span class="k">[coraza]</span>
</span></span><span class="line"><span class="cl"><span class="na">spoe-agent coraza-agent</span>
</span></span><span class="line"><span class="cl">    <span class="na">messages coraza-req</span>
</span></span><span class="line"><span class="cl">    <span class="na">option var-prefix coraza</span>
</span></span><span class="line"><span class="cl">    <span class="na">option set-on-error error</span>
</span></span><span class="line"><span class="cl">    <span class="na">timeout processing 500ms</span>
</span></span><span class="line"><span class="cl">    <span class="na">use-backend coraza-spoa</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="na">spoe-message coraza-req</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># Arguments are required to be in this order</span>
</span></span><span class="line"><span class="cl">    <span class="na">args app</span><span class="o">=</span><span class="s">str(haproxy_waf) src-ip=src src-port=src_port dst-ip=dst dst-port=dst_port method=method path=path query=query version=req.ver headers=req.hdrs body=req.body
</span></span></span><span class="line"><span class="cl"><span class="s">    event on-frontend-http-request</span>
</span></span></code></pre></div><h2 id="step-10-validate-and-start-haproxy">Step 10: Validate and Start HAProxy <a class="anchor" data-pagefind-ignore href="#step-10-validate-and-start-haproxy" aria-label="Link to this section">#</a></h2>
<p>Check the configuration before you restart HAProxy.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">haproxy -c -V -f /etc/haproxy/haproxy.cfg
</span></span></code></pre></div><p>If there are no errors, enable and restart HAProxy:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl"><span class="c1"># Enable HAProxy</span>
</span></span><span class="line"><span class="cl">systemctl <span class="nb">enable</span> haproxy.service
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Restart HAProxy (the Ubuntu/Debian package already started it with the</span>
</span></span><span class="line"><span class="cl"><span class="c1"># default configuration, so &#34;start&#34; would not load the new one)</span>
</span></span><span class="line"><span class="cl">systemctl restart haproxy.service
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Verify status</span>
</span></span><span class="line"><span class="cl">systemctl status haproxy.service
</span></span></code></pre></div><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Cause / fix</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Every request gets a 500</td>
					<td>HAProxy cannot reach the agent: check <code>systemctl status coraza-spoa</code> and that it listens on <code>127.0.0.1:9000</code></td>
			</tr>
			<tr>
					<td>Legitimate requests get a 403</td>
					<td>A CRS false positive: check the Coraza logs for the rule ID; run in <code>DetectionOnly</code> while tuning</td>
			</tr>
			<tr>
					<td>Agent does not start</td>
					<td>A rule file fails to load: check the agent&rsquo;s log in <code>/var/log/coraza-spoa/</code></td>
			</tr>
	</tbody>
</table>
<h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Fail closed.</strong> The <code>txn.coraza.error</code> rule blocks requests when the WAF is down. Remove it only if availability matters more than protection.</li>
<li><strong>Agent on localhost.</strong> Keep <code>bind: 127.0.0.1:9000</code>; anyone who can talk to the agent can see request data.</li>
<li><strong>Keep the CRS current.</strong> Update the rules with new CRS releases.</li>
<li><strong>A WAF is an extra layer.</strong> It does not replace patching and input validation in the application.</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-coraza" rel="noopener">pderuiter/blog-haproxy-coraza</a>. It creates an Ubuntu 24.04 VM, installs HAProxy from the official packages, builds Coraza-SPOA with the Core Rule Set and wires it into HAProxy; <code>terraform apply</code> followed by <code>ansible-playbook site.yml</code> gives you the blocking WAF from this guide.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>You&rsquo;ve now set up Coraza-SPOA integrated with HAProxy: a WAF that checks every request against the Core Rule Set before it reaches your application. Coraza can inspect both incoming and outgoing traffic; this setup checks requests (response inspection needs <code>response_check: true</code> and a <code>coraza-res</code> SPOE message).</p>
<p>For more information and additional configurations, visit:</p>
<ul>
<li><a href="https://github.com/corazawaf/coraza-spoa" rel="noopener">Coraza-SPOA GitHub</a></li>
<li><a href="https://github.com/haproxy/haproxy/blob/master/doc/SPOE.txt" rel="noopener">HAProxy Documentation for SPOE</a></li>
</ul>
<p>Start in detection mode on a real site, tune the false positives, then switch to blocking.</p>
]]></content:encoded></item><item><title>Automatic Disk Decryption with Tang</title><link>https://blog.bsdserver.nl/automatic-disk-decryption-with-tang/</link><guid isPermaLink="false">693b4fc079eb54000160a43d</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Thu, 11 Dec 2025 23:12:00 +0000</pubDate><description>If you're setting up disk encryption on your Red Hat Enterprise Linux 9 (RHEL9) servers, using a Tang server can be a smart choice to streamline the…</description><category>Linux</category><category>Security</category><category>Ansible</category><category>RHEL</category><category>Encryption</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/linux-tang-disk-decryption.png" medium="image"/><content:encoded><![CDATA[<p>If you&rsquo;re setting up disk encryption on your Red Hat Enterprise Linux 9 (RHEL9) servers, every reboot asks for a passphrase. In a server farm that means someone at a console for each reboot, which makes automated restarts and patching impractical.</p>
<p>This post deploys a Tang server with Ansible and configures RHEL9 clients through Kickstart, so encrypted volumes unlock automatically at boot as long as the Tang server is reachable.</p>
<h2 id="why-tang">Why Tang? <a class="anchor" data-pagefind-ignore href="#why-tang" aria-label="Link to this section">#</a></h2>
<p>Encryption at rest keeps data unreadable when a disk or server is stolen. Tang removes the operational cost of it:</p>
<ul>
<li><strong>Unattended reboots</strong> - Clients unlock their LUKS volumes over the network, no passphrase typed.</li>
<li><strong>Location-bound unlocking</strong> - A disk only unlocks while it can reach your Tang server. Taken out of the network, it stays locked.</li>
<li><strong>Lightweight</strong> - Tang is a small HTTP service with nothing to manage per client.</li>
<li><strong>Repeatable</strong> - Ansible sets up the server, Kickstart sets up the clients, so every machine is configured the same way.</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> for encrypted servers in a data centre or edge location that must reboot without someone typing a passphrase.</li>
<li><strong>Skip it</strong> for a single machine you reboot by hand, or a machine that is not on a trusted network at boot (a laptop). A passphrase or TPM is simpler there.</li>
</ul>
<h2 id="how-it-works">How It Works <a class="anchor" data-pagefind-ignore href="#how-it-works" aria-label="Link to this section">#</a></h2>
<p>Tang works together with Clevis, the client-side tool that hooks into LUKS.</p>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Tang (<code>tangd.socket</code>)</td>
					<td>Tang server</td>
					<td>Answers Clevis requests over HTTP so the client can recover its key.</td>
			</tr>
			<tr>
					<td>Clevis + <code>clevis-dracut</code></td>
					<td>Each encrypted client</td>
					<td>Binds the LUKS volume to Tang and contacts Tang from the initramfs at boot.</td>
			</tr>
			<tr>
					<td>LUKS</td>
					<td>Each encrypted client</td>
					<td>The disk encryption itself. The original passphrase keeps working as a fallback.</td>
			</tr>
	</tbody>
</table>
<p>The flow: client boots → initramfs brings up the network → Clevis contacts Tang → the LUKS key is recovered → the volume unlocks → boot continues.</p>
<h2 id="prerequisites">Prerequisites <a class="anchor" data-pagefind-ignore href="#prerequisites" aria-label="Link to this section">#</a></h2>
<ol>
<li><strong>Red Hat Enterprise Linux 9 (RHEL9) Server</strong>: This tutorial assumes that you are using RHEL9. Make sure the system is installed and configured.</li>
<li><strong>Root or Sudo Access</strong>: You will need root privileges to install packages and configure services.</li>
<li><strong>Ansible Installed</strong>: Ansible should be installed on the control node to automate the deployment process.</li>
<li><strong>FirewallD Installed and Configured</strong>: The playbook assumes you are using FirewallD for managing firewall rules.</li>
<li><strong>Network Connectivity</strong>: Ensure that the Tang server and any client machines can communicate over the network.</li>
<li><strong>Clevis Installed on Clients</strong>: If you plan to use Tang to automate decryption, Clevis must be installed on the client systems.</li>
</ol>
<h2 id="deploying-the-tang-server-with-ansible">Deploying the Tang Server with Ansible <a class="anchor" data-pagefind-ignore href="#deploying-the-tang-server-with-ansible" aria-label="Link to this section">#</a></h2>
<p>Setting up Tang by hand is quick, but you want more than one Tang server for redundancy. A playbook keeps them identical.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl">- <span class="nt">hosts</span><span class="p">:</span><span class="w"> </span><span class="l">tang_server</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">become</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">tasks</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># Install packages required for Tang server</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Install required packages for Tang server</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ansible.builtin.package</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">name</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- <span class="l">tang</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- <span class="l">httpd</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">present</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># Configure firewall rules for Tang server</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Configure firewall for Tang server</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ansible.posix.firewalld</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">service</span><span class="p">:</span><span class="w"> </span><span class="l">http</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">permanent</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">enabled</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">immediate</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># Start and enable Tang server</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Start and enable Tang server</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ansible.builtin.systemd</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">tangd.socket</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">enabled</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">started</span><span class="w">
</span></span></span></code></pre></div><p>What each task does:</p>
<ul>
<li><strong>Install packages</strong>: installs <code>tang</code> (and <code>httpd</code>).</li>
<li><strong>Firewall</strong>: Tang talks plain HTTP, so the <code>http</code> service (port 80) is opened. <code>immediate: true</code> applies the rule now as well as permanently, without a separate reload.</li>
<li><strong><code>tangd.socket</code></strong>: socket activation. systemd listens on the port and starts Tang per request; <code>enabled: true</code> makes it survive reboots.</li>
</ul>
<h2 id="configuring-the-clients-with-kickstart">Configuring the Clients with Kickstart <a class="anchor" data-pagefind-ignore href="#configuring-the-clients-with-kickstart" aria-label="Link to this section">#</a></h2>
<p>The client side is done at install time: encrypt the volume, install Clevis, and bind the volume to Tang.</p>
<h3 id="finding-the-luks-volume-uuid">Finding the LUKS Volume UUID <a class="anchor" data-pagefind-ignore href="#finding-the-luks-volume-uuid" aria-label="Link to this section">#</a></h3>
<p>You need to know which LUKS volume to bind. To look it up during the Kickstart installation:</p>
<ol>
<li><strong>Open a terminal</strong>: press <code>Ctrl+Alt+F2</code> during the installation.</li>
<li><strong>Find the partition</strong>: run <code>lsblk</code> and locate the encrypted device (e.g. <code>/dev/sda3</code>).</li>
<li><strong>Read its UUID</strong>:</li>
</ol>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo cryptsetup luksUUID /dev/sda3
</span></span></code></pre></div><p>Replace <code>/dev/sda3</code> with your device. The output is the <code>volume-UUID</code> of that LUKS partition, which identifies the volume in your Kickstart configuration.</p>
<h3 id="the-kickstart-snippet">The Kickstart Snippet <a class="anchor" data-pagefind-ignore href="#the-kickstart-snippet" aria-label="Link to this section">#</a></h3>
<p>This snippet installs Clevis, creates the encrypted volume and binds it to Tang in one installation run.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Install Clevis for client-side automation</span>
</span></span><span class="line"><span class="cl">%packages
</span></span><span class="line"><span class="cl">@core
</span></span><span class="line"><span class="cl">clevis
</span></span><span class="line"><span class="cl">clevis-dracut
</span></span><span class="line"><span class="cl">%end
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Partition and encrypt the logical volume</span>
</span></span><span class="line"><span class="cl">part pv.01 --size<span class="o">=</span><span class="m">1</span> --grow --encrypted --passphrase<span class="o">=</span>&lt;dummy-passphrase&gt;
</span></span><span class="line"><span class="cl">volgroup vg01 pv.01
</span></span><span class="line"><span class="cl">logvol / --fstype<span class="o">=</span><span class="s2">&#34;ext4&#34;</span> --name<span class="o">=</span>root --vgname<span class="o">=</span>vg01 --size<span class="o">=</span><span class="m">20480</span> --encrypted --passphrase<span class="o">=</span>&lt;dummy-passphrase&gt;
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Set up Clevis to use Tang for decryption</span>
</span></span><span class="line"><span class="cl">%post
</span></span><span class="line"><span class="cl"><span class="c1"># Bind the LUKS volume to Tang server for automatic decryption</span>
</span></span><span class="line"><span class="cl">clevis luks <span class="nb">bind</span> -d /dev/mapper/vg01-root tang <span class="s1">&#39;{&#34;url&#34;: &#34;http://&lt;Tang-server-IP&gt;:80&#34;}&#39;</span>
</span></span><span class="line"><span class="cl">%end
</span></span></code></pre></div><table>
	<thead>
			<tr>
					<th>Section</th>
					<th>What it does</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>%packages</code></td>
					<td><code>clevis</code> for binding, <code>clevis-dracut</code> so the initramfs can unlock at boot.</td>
			</tr>
			<tr>
					<td><code>part</code> / <code>volgroup</code> / <code>logvol</code></td>
					<td>Creates the encrypted volume with a temporary passphrase. Replace it after installation.</td>
			</tr>
			<tr>
					<td><code>%post</code></td>
					<td><code>clevis luks bind</code> adds a Tang-based key to the LUKS volume. From then on, boot unlocks it via Tang.</td>
			</tr>
	</tbody>
</table>
<h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Keep the passphrase.</strong> The <code>&lt;dummy-passphrase&gt;</code> stays a valid key. Change it to a strong one and store it safely; it is your fallback when Tang is unreachable.</li>
<li><strong>Tang reachable = disk unlockable.</strong> Anyone with the disk and network access to Tang can unlock it. Only expose Tang on the internal network where your servers boot.</li>
<li><strong>Run more than one Tang server.</strong> If the only Tang server is down, clients wait for the passphrase at boot.</li>
</ul>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>With a few lines of Ansible you have a Tang server, and with a Kickstart snippet every new client binds to it at install time. Encrypted servers can then reboot unattended, whether you run a handful or hundreds.</p>
<p>Give this Ansible playbook a try, and let me know how it works for you! If you have any questions or run into any challenges, feel free to leave a comment.</p>
]]></content:encoded></item></channel></rss>