<?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>Networking | A DevOps Blog</title><link>https://blog.bsdserver.nl/tag/networking/</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/networking/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 DNS Load Balancing: High Availability for DNS Infrastructure</title><link>https://blog.bsdserver.nl/haproxy-dns-load-balancing-high-availability-for-dns-infrastructure/</link><guid isPermaLink="false">693b727a79eb54000160a5e9</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:40:11 +0000</pubDate><description>DNS is critical infrastructure - when DNS fails, nothing works.</description><category>HAProxy</category><category>DNS</category><category>Load balancing</category><category>High availability</category><category>Networking</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/haproxy-dns-loadbalancing.png" medium="image"/><content:encoded><![CDATA[<p>DNS is critical infrastructure - when DNS fails, nothing works. Clients usually have two resolver addresses at most, and a dead server behind one of them means slow lookups everywhere.</p>
<p>This guide puts a load balancer in front of resolvers and authoritative servers. HAProxy handles DNS over TCP and DNS over TLS; dnsdist handles DNS over UDP next to it, because HAProxy cannot proxy UDP. keepalived makes the load balancer itself redundant.</p>
<h2 id="why-load-balance-dns">Why Load Balance DNS? <a class="anchor" data-pagefind-ignore href="#why-load-balance-dns" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>High availability</strong>: If one DNS server fails, queries go to the healthy ones</li>
<li><strong>Performance</strong>: Spread queries over several servers</li>
<li><strong>Maintenance flexibility</strong>: Take a server offline without clients noticing</li>
<li><strong>Both protocols</strong>: UDP and TCP on one address</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 many clients depend on a few DNS servers, or when you want one stable address in front of a changing set of servers.</li>
<li><strong>Skip it</strong> when clients already list two or three resolvers and can live with a short timeout on failure. The load balancer pair is two more machines to run.</li>
</ul>
<h2 id="dns-protocol-considerations">DNS Protocol Considerations <a class="anchor" data-pagefind-ignore href="#dns-protocol-considerations" aria-label="Link to this section">#</a></h2>
<p>DNS primarily uses UDP on port 53, but can fall back to TCP for:</p>
<ul>
<li>Responses larger than 512 bytes (or EDNS0 buffer size)</li>
<li>Zone transfers (AXFR/IXFR)</li>
<li>DNS over TCP enforcement</li>
</ul>
<p>HAProxy only handles the TCP side. The community edition has no UDP proxy mode: <code>bind ... udp</code> and <code>mode udp</code> are rejected as unknown keywords, also in HAProxy 3.4. So the work is split:</p>
<table>
	<thead>
			<tr>
					<th>Traffic</th>
					<th>Handled by</th>
					<th>Why</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>UDP port 53</td>
					<td><a href="https://www.dnsdist.org/" rel="noopener">dnsdist</a></td>
					<td>A DNS-aware load balancer from PowerDNS; HAProxy has no UDP proxy</td>
			</tr>
			<tr>
					<td>TCP port 53</td>
					<td>HAProxy</td>
					<td>Large responses, zone transfers</td>
			</tr>
			<tr>
					<td>TCP port 853 (DoT)</td>
					<td>HAProxy</td>
					<td>TLS termination or passthrough</td>
			</tr>
	</tbody>
</table>
<h2 id="architecture-overview">Architecture Overview <a class="anchor" data-pagefind-ignore href="#architecture-overview" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>dnsdist</td>
					<td>Both load balancers</td>
					<td>Balances UDP queries, health-checks the servers, rate limits per client.</td>
			</tr>
			<tr>
					<td>nftables</td>
					<td>Both load balancers</td>
					<td>Redirects UDP port 53 to dnsdist on port 5353, because TCP port 53 belongs to HAProxy.</td>
			</tr>
			<tr>
					<td>HAProxy</td>
					<td>Both load balancers</td>
					<td>Balances DNS over TCP and DoT.</td>
			</tr>
			<tr>
					<td>keepalived</td>
					<td>Both load balancers</td>
					<td>Moves the virtual IPs to the backup when HAProxy or dnsdist stops.</td>
			</tr>
			<tr>
					<td>DNS servers</td>
					<td>Separate machines</td>
					<td>Resolvers (<code>192.168.1.10-12</code>) and authoritative servers (<code>192.168.1.20-22</code>).</td>
			</tr>
	</tbody>
</table>
<p>The flow: client → virtual IP → UDP: nftables → dnsdist, TCP: HAProxy → healthy DNS server.</p>
<h2 id="basic-udp-dns-load-balancing">Basic UDP DNS Load Balancing <a class="anchor" data-pagefind-ignore href="#basic-udp-dns-load-balancing" aria-label="Link to this section">#</a></h2>
<p>dnsdist runs on the same machine as HAProxy, so clients use one address for both protocols.</p>
<p>Install dnsdist from the official PowerDNS repository (dnsdist 2.1 on Ubuntu 24.04):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">install -d /etc/apt/keyrings
</span></span><span class="line"><span class="cl">curl https://repo.powerdns.com/FD380FBB-pub.asc -o /etc/apt/keyrings/dnsdist-21-pub.asc
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;deb [signed-by=/etc/apt/keyrings/dnsdist-21-pub.asc] http://repo.powerdns.com/ubuntu noble-dnsdist-21 main&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  &gt; /etc/apt/sources.list.d/pdns.list
</span></span><span class="line"><span class="cl">cat &gt; /etc/apt/preferences.d/dnsdist <span class="s">&lt;&lt; EOF
</span></span></span><span class="line"><span class="cl"><span class="s">Package: dnsdist*
</span></span></span><span class="line"><span class="cl"><span class="s">Pin: origin repo.powerdns.com
</span></span></span><span class="line"><span class="cl"><span class="s">Pin-Priority: 600
</span></span></span><span class="line"><span class="cl"><span class="s">EOF</span>
</span></span><span class="line"><span class="cl">apt update
</span></span><span class="line"><span class="cl">apt install dnsdist nftables
</span></span></code></pre></div><p>On Debian 13 use <code>http://repo.powerdns.com/debian trixie-dnsdist-21 main</code> instead.</p>
<p>dnsdist always listens on UDP and TCP together, and TCP port 53 belongs to HAProxy. So dnsdist listens on port 5353, and an nftables rule hands it the UDP traffic for port 53.</p>
<ul>
<li><code>addLocal</code>: the listen address.</li>
<li><code>newServer</code>: one line per DNS server.</li>
<li><code>setServerPolicy(roundrobin)</code>: queries in turn over all healthy servers.</li>
</ul>
<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">-- UDP port 53 is redirected here by nftables; HAProxy owns TCP port 53</span>
</span></span><span class="line"><span class="cl"><span class="n">addLocal</span><span class="p">(</span><span class="s1">&#39;0.0.0.0:5353&#39;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">-- dnsdist only answers private (RFC1918) clients by default; widen with setACL() if needed</span>
</span></span><span class="line"><span class="cl">
</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="s1">&#39;192.168.1.10:53&#39;</span><span class="p">,</span> <span class="n">name</span> <span class="o">=</span> <span class="s1">&#39;dns1&#39;</span> <span class="p">})</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="s1">&#39;192.168.1.11:53&#39;</span><span class="p">,</span> <span class="n">name</span> <span class="o">=</span> <span class="s1">&#39;dns2&#39;</span> <span class="p">})</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="s1">&#39;192.168.1.12:53&#39;</span><span class="p">,</span> <span class="n">name</span> <span class="o">=</span> <span class="s1">&#39;dns3&#39;</span> <span class="p">})</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">setServerPolicy</span><span class="p">(</span><span class="n">roundrobin</span><span class="p">)</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="c1"># /etc/nftables.conf (add below the existing tables)</span>
</span></span><span class="line"><span class="cl">table ip dns_udp <span class="o">{</span>
</span></span><span class="line"><span class="cl">    chain prerouting <span class="o">{</span>
</span></span><span class="line"><span class="cl">        <span class="nb">type</span> nat hook prerouting priority dstnat<span class="p">;</span> policy accept<span class="p">;</span>
</span></span><span class="line"><span class="cl">        udp dport <span class="m">53</span> redirect to :5353
</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><p>Load both and start dnsdist:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">dnsdist --check-config
</span></span><span class="line"><span class="cl">systemctl <span class="nb">enable</span> --now nftables
</span></span><span class="line"><span class="cl">systemctl restart dnsdist
</span></span></code></pre></div><p><strong>Warning before you enable <code>nftables.service</code>:</strong> the stock <code>/etc/nftables.conf</code> on Debian and Ubuntu starts with <code>flush ruleset</code>. Loading it removes every other nftables rule on the host, including the iptables-nft rules that Docker, ufw and firewalld create.</p>
<ul>
<li>Run this on dedicated load balancer machines, or leave <code>flush ruleset</code> out and load the <code>dns_udp</code> table from its own file.</li>
<li>The companion repo below adds the table to <code>/etc/nftables.conf</code> in the same way, so it is meant for dedicated load balancer VMs and its README warns about this.</li>
</ul>
<p>What dnsdist does without extra configuration:</p>
<ul>
<li><strong>Health checks</strong>: every server once a second, with a query for <code>a.root-servers.net</code>. Any answer except SERVFAIL counts as up.</li>
<li><strong>Failover</strong>: failing servers leave the rotation until they answer again.</li>
<li><strong>Client addresses</strong>: kept, so per-client rate limits (below) keep working.</li>
</ul>
<h2 id="tcp-dns-load-balancing">TCP DNS Load Balancing <a class="anchor" data-pagefind-ignore href="#tcp-dns-load-balancing" aria-label="Link to this section">#</a></h2>
<p>HAProxy takes TCP port 53 in <code>mode tcp</code>: it passes the connection through without parsing DNS.</p>
<ul>
<li><code>option tcp-check</code> with <code>check</code>: a server is up when it accepts a TCP connection.</li>
<li><code>timeout client</code> / <code>timeout server 30s</code>: room for zone transfers and slow large answers.</li>
</ul>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend dns_tcp
    bind *:53
    mode tcp
    option tcplog
    timeout client 30s
    default_backend dns_servers_tcp

backend dns_servers_tcp
    mode tcp
    balance roundrobin
    timeout server 30s
    timeout connect 5s
    option tcp-check
    server dns1 192.168.1.10:53 check
    server dns2 192.168.1.11:53 check
    server dns3 192.168.1.12:53 check
</code></pre><h2 id="combined-udp-and-tcp-configuration">Combined UDP and TCP Configuration <a class="anchor" data-pagefind-ignore href="#combined-udp-and-tcp-configuration" aria-label="Link to this section">#</a></h2>
<p>A production DNS load balancer should handle both protocols. dnsdist from the previous section takes UDP; HAProxy takes TCP, with health checks and statistics.</p>
<ul>
<li><code>defaults dns</code>: short timeouts (DNS answers fast) and <code>default-server inter 3s fall 3 rise 2</code>: check every 3 seconds, down after 3 failures, up after 2 successes.</li>
<li><code>listen stats</code>: stats page on <code>:8404/stats</code>, Prometheus metrics on <code>:8404/metrics</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 100000
    nbthread 4

defaults dns
    log global
    timeout connect 1s
    timeout client  5s
    timeout server  5s
    default-server inter 3s fall 3 rise 2

# UDP DNS is handled by dnsdist (see above)

# TCP DNS
frontend dns_tcp_frontend
    bind *:53
    mode tcp
    option tcplog
    default_backend dns_tcp_backend

backend dns_tcp_backend
    mode tcp
    balance roundrobin
    option tcp-check
    server dns1 192.168.1.10:53 check
    server dns2 192.168.1.11:53 check
    server dns3 192.168.1.12:53 check

# Stats interface
listen stats
    bind *:8404
    mode http
    stats enable
    stats uri /stats
    stats refresh 5s
    http-request use-service prometheus-exporter if { path /metrics }
</code></pre><h2 id="dns-health-checks">DNS Health Checks <a class="anchor" data-pagefind-ignore href="#dns-health-checks" aria-label="Link to this section">#</a></h2>
<p>Pick the check by how much you need to know about the server:</p>
<table>
	<thead>
			<tr>
					<th>Check</th>
					<th>Proves</th>
					<th>Cost</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>TCP connect</td>
					<td>The port accepts connections</td>
					<td>Lowest</td>
			</tr>
			<tr>
					<td>DNS query in <code>tcp-check</code></td>
					<td>The server answers a real query</td>
					<td>Hand-built packet</td>
			</tr>
			<tr>
					<td>External script</td>
					<td>Anything a script can test</td>
					<td>A process per check; needs <code>insecure-fork-wanted</code></td>
			</tr>
	</tbody>
</table>
<h3 id="basic-tcp-health-check">Basic TCP Health Check <a class="anchor" data-pagefind-ignore href="#basic-tcp-health-check" aria-label="Link to this section">#</a></h3>
<p>The simplest check verifies the TCP port is responding. It does not notice a server that accepts connections but cannot answer.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">backend dns_tcp_backend
    mode tcp
    option tcp-check
    server dns1 192.168.1.10:53 check inter 2s fall 3 rise 2
</code></pre><h3 id="dns-specific-health-check">DNS-Specific Health Check <a class="anchor" data-pagefind-ignore href="#dns-specific-health-check" aria-label="Link to this section">#</a></h3>
<p>For more thorough checking, verify the server can resolve queries. The check sends a query for <code>health.local</code> and expects a response with no error.</p>
<ul>
<li>Every server needs a <code>health.local</code> A record: an NXDOMAIN answer does not match and marks the server down.</li>
<li>The 2-byte length prefix comes first because DNS over TCP requires it.</li>
</ul>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">backend dns_tcp_backend
    mode tcp
    option tcp-check
    
    # DNS query for &#34;health.local&#34; A record
    # This is a raw DNS query packet (DNS over TCP needs the 2-byte length prefix)
    tcp-check connect port 53
    tcp-check send-binary 001e  # Length: 30-byte query follows
    tcp-check send-binary 0000  # Transaction ID
    tcp-check send-binary 0100  # Flags: Standard query
    tcp-check send-binary 0001  # Questions: 1
    tcp-check send-binary 0000  # Answer RRs: 0
    tcp-check send-binary 0000  # Authority RRs: 0
    tcp-check send-binary 0000  # Additional RRs: 0
    tcp-check send-binary 066865616c7468  # &#34;health&#34;
    tcp-check send-binary 056c6f63616c    # &#34;local&#34;
    tcp-check send-binary 00              # End of name
    tcp-check send-binary 0001  # Type: A
    tcp-check send-binary 0001  # Class: IN
    tcp-check expect rbinary ^[0-9A-Fa-f]{8}8[15]80  # Response flags: answer, no error (AA bit optional)
    
    server dns1 192.168.1.10:53 check
</code></pre><h3 id="external-health-check-script">External Health Check Script <a class="anchor" data-pagefind-ignore href="#external-health-check-script" aria-label="Link to this section">#</a></h3>
<p>For complex health checks, use an external script. This needs <code>external-check</code> and <code>insecure-fork-wanted</code> in the <code>global</code> section, otherwise HAProxy refuses the configuration.</p>
<p><code>insecure-fork-wanted</code> lets HAProxy start processes, which it blocks by default for safety. Only use it when the other checks are not enough.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">global
    external-check
    insecure-fork-wanted

backend dns_tcp_backend
    mode tcp
    option external-check
    external-check path &#34;/usr/bin:/bin&#34;
    external-check command /etc/haproxy/check-dns.sh
    server dns1 192.168.1.10:53 check inter 5s
</code></pre><p>Create the health check script. HAProxy passes the server address and port; exit code 0 means up. The script resolves <code>google.com</code>, so it suits resolvers; for authoritative servers, query a zone they serve.</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/haproxy/check-dns.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Arguments from HAProxy:</span>
</span></span><span class="line"><span class="cl"><span class="c1"># $1 = proxy address, $2 = proxy port (NOT_USED for a backend)</span>
</span></span><span class="line"><span class="cl"><span class="c1"># $3 = server address</span>
</span></span><span class="line"><span class="cl"><span class="c1"># $4 = server port</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">SERVER</span><span class="o">=</span><span class="nv">$3</span>
</span></span><span class="line"><span class="cl"><span class="nv">PORT</span><span class="o">=</span><span class="nv">$4</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Try to resolve a known domain</span>
</span></span><span class="line"><span class="cl"><span class="k">if</span> dig @<span class="si">${</span><span class="nv">SERVER</span><span class="si">}</span> -p <span class="si">${</span><span class="nv">PORT</span><span class="si">}</span> +time<span class="o">=</span><span class="m">2</span> +tries<span class="o">=</span><span class="m">1</span> google.com A &gt; /dev/null 2&gt;<span class="p">&amp;</span>1<span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">    <span class="nb">exit</span> <span class="m">0</span>  <span class="c1"># Success</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">exit</span> <span class="m">1</span>  <span class="c1"># Failure</span>
</span></span><span class="line"><span class="cl"><span class="k">fi</span>
</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/haproxy/check-dns.sh
</span></span></code></pre></div><h2 id="load-balancing-algorithms-for-dns">Load Balancing Algorithms for DNS <a class="anchor" data-pagefind-ignore href="#load-balancing-algorithms-for-dns" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Algorithm</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>roundrobin</code></td>
					<td>The default: equal servers, even spread</td>
			</tr>
			<tr>
					<td><code>leastconn</code></td>
					<td>TCP connections of uneven length, like zone transfers</td>
			</tr>
			<tr>
					<td><code>source</code></td>
					<td>Keeping each client on one resolver, so its cache is reused</td>
			</tr>
			<tr>
					<td><code>first</code></td>
					<td>Active-passive: everything to one server until it fails</td>
			</tr>
	</tbody>
</table>
<h3 id="round-robin">Round Robin <a class="anchor" data-pagefind-ignore href="#round-robin" aria-label="Link to this section">#</a></h3>
<p>Default algorithm, distributes queries evenly:</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">backend dns_servers
    balance roundrobin
    server dns1 192.168.1.10:53 check
    server dns2 192.168.1.11:53 check
</code></pre><h3 id="least-connections-tcp-only">Least Connections (TCP only) <a class="anchor" data-pagefind-ignore href="#least-connections-tcp-only" aria-label="Link to this section">#</a></h3>
<p>Best for DNS servers with varying query complexity:</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">backend dns_tcp_backend
    mode tcp
    balance leastconn
    server dns1 192.168.1.10:53 check
    server dns2 192.168.1.11:53 check
</code></pre><h3 id="source-ip-hash">Source IP Hash <a class="anchor" data-pagefind-ignore href="#source-ip-hash" aria-label="Link to this section">#</a></h3>
<p>Ensures clients consistently reach the same server (useful for caching). <code>hash-type consistent</code> keeps most clients on their server when one is added or removed.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">backend dns_servers
    balance source
    hash-type consistent
    server dns1 192.168.1.10:53 check
    server dns2 192.168.1.11:53 check
</code></pre><h3 id="first-available">First Available <a class="anchor" data-pagefind-ignore href="#first-available" aria-label="Link to this section">#</a></h3>
<p>Send all traffic to the first available server (active-passive). The <code>backup</code> server only gets traffic when the first is down.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">backend dns_servers
    balance first
    server dns-primary   192.168.1.10:53 check
    server dns-secondary 192.168.1.11:53 check backup
</code></pre><h2 id="recursive-vs-authoritative-dns">Recursive vs Authoritative DNS <a class="anchor" data-pagefind-ignore href="#recursive-vs-authoritative-dns" aria-label="Link to this section">#</a></h2>
<p>The two server types need different settings:</p>
<table>
	<thead>
			<tr>
					<th></th>
					<th>Recursive resolvers</th>
					<th>Authoritative servers</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Clients</td>
					<td>Internal only</td>
					<td>Anyone on the internet</td>
			</tr>
			<tr>
					<td>Address</td>
					<td><code>10.0.0.1</code> / <code>10.0.0.53</code></td>
					<td><code>203.0.113.53</code></td>
			</tr>
			<tr>
					<td>Fallback</td>
					<td>Public DNS when all internal resolvers are down</td>
					<td>None: only your servers have your zones</td>
			</tr>
			<tr>
					<td>dnsdist ACL</td>
					<td>Default (private clients only)</td>
					<td>Open to all</td>
			</tr>
	</tbody>
</table>
<h3 id="load-balancing-recursive-resolvers">Load Balancing Recursive Resolvers <a class="anchor" data-pagefind-ignore href="#load-balancing-recursive-resolvers" aria-label="Link to this section">#</a></h3>
<p>For caching resolvers serving internal clients, HAProxy takes TCP. The public resolvers are <code>backup</code> servers: they only get traffic when both internal resolvers are down.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend dns_resolver
    bind 10.0.0.1:53
    mode tcp
    default_backend resolvers

backend resolvers
    mode tcp
    balance roundrobin
    # Internal resolvers
    server resolver1 192.168.1.10:53 check weight 100
    server resolver2 192.168.1.11:53 check weight 100
    # Public fallback
    server cloudflare 1.1.1.1:53 check weight 50 backup
    server google     8.8.8.8:53 check weight 50 backup
</code></pre><p>And dnsdist takes UDP (with the nftables redirect from above), using a pool for the internal resolvers and one for the public fallback.</p>
<ul>
<li><code>pool</code>: groups servers. Rules pick a pool per query.</li>
<li><code>addAction</code> rules run in order: the first that matches decides. <code>PoolAvailableRule('internal')</code> matches while at least one internal resolver is up.</li>
</ul>
<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 class="n">addLocal</span><span class="p">(</span><span class="s1">&#39;0.0.0.0:5353&#39;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">-- Internal resolvers</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="s1">&#39;192.168.1.10:53&#39;</span><span class="p">,</span> <span class="n">name</span> <span class="o">=</span> <span class="s1">&#39;resolver1&#39;</span><span class="p">,</span> <span class="n">pool</span> <span class="o">=</span> <span class="s1">&#39;internal&#39;</span> <span class="p">})</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="s1">&#39;192.168.1.11:53&#39;</span><span class="p">,</span> <span class="n">name</span> <span class="o">=</span> <span class="s1">&#39;resolver2&#39;</span><span class="p">,</span> <span class="n">pool</span> <span class="o">=</span> <span class="s1">&#39;internal&#39;</span> <span class="p">})</span>
</span></span><span class="line"><span class="cl"><span class="c1">-- Public fallback</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="s1">&#39;1.1.1.1:53&#39;</span><span class="p">,</span> <span class="n">name</span> <span class="o">=</span> <span class="s1">&#39;cloudflare&#39;</span><span class="p">,</span> <span class="n">pool</span> <span class="o">=</span> <span class="s1">&#39;fallback&#39;</span> <span class="p">})</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="s1">&#39;8.8.8.8:53&#39;</span><span class="p">,</span> <span class="n">name</span> <span class="o">=</span> <span class="s1">&#39;google&#39;</span><span class="p">,</span> <span class="n">pool</span> <span class="o">=</span> <span class="s1">&#39;fallback&#39;</span> <span class="p">})</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">setServerPolicy</span><span class="p">(</span><span class="n">roundrobin</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">-- Internal resolvers while at least one is up, public DNS otherwise</span>
</span></span><span class="line"><span class="cl"><span class="n">addAction</span><span class="p">(</span><span class="n">PoolAvailableRule</span><span class="p">(</span><span class="s1">&#39;internal&#39;</span><span class="p">),</span> <span class="n">PoolAction</span><span class="p">(</span><span class="s1">&#39;internal&#39;</span><span class="p">))</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">PoolAction</span><span class="p">(</span><span class="s1">&#39;fallback&#39;</span><span class="p">))</span>
</span></span></code></pre></div><h3 id="load-balancing-authoritative-servers">Load Balancing Authoritative Servers <a class="anchor" data-pagefind-ignore href="#load-balancing-authoritative-servers" aria-label="Link to this section">#</a></h3>
<p>For authoritative servers serving external queries. They listen on their own public address, separate from the internal resolvers.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend dns_authoritative
    bind 203.0.113.53:53
    mode tcp
    default_backend auth_servers

backend auth_servers
    mode tcp
    balance roundrobin
    option tcp-check
    server auth1 192.168.1.20:53 check
    server auth2 192.168.1.21:53 check
    server auth3 192.168.1.22:53 check
</code></pre><p>The UDP side in dnsdist; an authoritative server answers anyone, so open the ACL:</p>
<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 class="n">addLocal</span><span class="p">(</span><span class="s1">&#39;0.0.0.0:5353&#39;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="n">setACL</span><span class="p">({</span> <span class="s1">&#39;0.0.0.0/0&#39;</span><span class="p">,</span> <span class="s1">&#39;::/0&#39;</span> <span class="p">})</span>
</span></span><span class="line"><span class="cl">
</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="s1">&#39;192.168.1.20:53&#39;</span><span class="p">,</span> <span class="n">name</span> <span class="o">=</span> <span class="s1">&#39;auth1&#39;</span> <span class="p">})</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="s1">&#39;192.168.1.21:53&#39;</span><span class="p">,</span> <span class="n">name</span> <span class="o">=</span> <span class="s1">&#39;auth2&#39;</span> <span class="p">})</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="s1">&#39;192.168.1.22:53&#39;</span><span class="p">,</span> <span class="n">name</span> <span class="o">=</span> <span class="s1">&#39;auth3&#39;</span> <span class="p">})</span>
</span></span></code></pre></div><h2 id="dns-over-tls-dot-load-balancing">DNS over TLS (DoT) Load Balancing <a class="anchor" data-pagefind-ignore href="#dns-over-tls-dot-load-balancing" aria-label="Link to this section">#</a></h2>
<p>For encrypted DNS traffic on port 853, pick one of two modes:</p>
<table>
	<thead>
			<tr>
					<th>Mode</th>
					<th>Where TLS ends</th>
					<th>Use it when</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Termination</td>
					<td>HAProxy, with <code>dns.example.com.pem</code></td>
					<td>The DNS servers only speak plain DNS. One certificate on the load balancer.</td>
			</tr>
			<tr>
					<td>Passthrough</td>
					<td>The DNS servers</td>
					<td>The servers already run DoT, or the load balancer should not see the queries.</td>
			</tr>
	</tbody>
</table>
<p>In passthrough mode, <code>check-ssl verify none</code> health-checks over TLS without verifying the server certificate.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy"># TLS Termination at HAProxy
frontend dot_frontend
    bind *:853 ssl crt /etc/haproxy/certs/dns.example.com.pem
    mode tcp
    option tcplog
    default_backend dns_tcp_backend

backend dns_tcp_backend
    mode tcp
    balance roundrobin
    server dns1 192.168.1.10:53 check
    server dns2 192.168.1.11:53 check

# TLS Passthrough (use either termination or passthrough on port 853, not both)
frontend dot_passthrough
    bind *:853
    mode tcp
    option tcplog
    default_backend dot_servers

backend dot_servers
    mode tcp
    balance roundrobin
    # check-ssl: health check over TLS, client traffic is passed through untouched
    server dot1 192.168.1.10:853 check check-ssl verify none
    server dot2 192.168.1.11:853 check check-ssl verify none
</code></pre><h2 id="rate-limiting-dns-queries">Rate Limiting DNS Queries <a class="anchor" data-pagefind-ignore href="#rate-limiting-dns-queries" aria-label="Link to this section">#</a></h2>
<p>Protect against DNS amplification attacks. Open DNS servers can be abused to send large answers to a spoofed victim address. For UDP, rate limit in dnsdist:</p>
<ul>
<li><code>MaxQPSIPRule(100)</code> with <code>DropAction()</code>: drops queries above 100 per second per client address.</li>
<li><code>TCAction()</code> for <code>ANY</code>: the client must retry over TCP, which needs a real handshake and so cannot be spoofed.</li>
</ul>
<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">-- Drop clients that send more than 100 queries per second</span>
</span></span><span class="line"><span class="cl"><span class="n">addAction</span><span class="p">(</span><span class="n">MaxQPSIPRule</span><span class="p">(</span><span class="mi">100</span><span class="p">),</span> <span class="n">DropAction</span><span class="p">())</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">-- Answer ANY queries with the TC bit, so the client has to retry over TCP (HAProxy)</span>
</span></span><span class="line"><span class="cl"><span class="n">addAction</span><span class="p">(</span><span class="n">QTypeRule</span><span class="p">(</span><span class="n">DNSQType.ANY</span><span class="p">),</span> <span class="n">TCAction</span><span class="p">())</span>
</span></span></code></pre></div><p>For TCP with more options. The stick table tracks each client address:</p>
<ul>
<li><code>conn_rate(10s)</code> above 50: new connections are rejected.</li>
<li><code>bytes_out_rate(10s)</code> above 100000: the connection is rejected, to cap how much one client can pull.</li>
</ul>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend dns_tcp
    bind *:53
    mode tcp
    option tcplog
    
    # Rate limiting table
    stick-table type ip size 100k expire 60s store conn_rate(10s),bytes_out_rate(10s)
    
    # Limit connections per IP
    tcp-request connection track-sc0 src
    tcp-request connection reject if { sc0_conn_rate gt 50 }
    
    # Limit bandwidth (prevent amplification)
    tcp-request content reject if { sc0_bytes_out_rate gt 100000 }
    
    default_backend dns_tcp_backend
</code></pre><h2 id="high-availability-haproxy-setup">High Availability HAProxy Setup <a class="anchor" data-pagefind-ignore href="#high-availability-haproxy-setup" aria-label="Link to this section">#</a></h2>
<p>For the load balancer itself, use keepalived for failover. Both nodes run HAProxy and dnsdist; the virtual IPs live on one node at a time.</p>
<p>The backup node must be able to bind the virtual IP before it owns it, so allow that 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="nb">echo</span> <span class="s1">&#39;net.ipv4.ip_nonlocal_bind = 1&#39;</span> &gt; /etc/sysctl.d/90-nonlocal-bind.conf
</span></span><span class="line"><span class="cl">sysctl --system
</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">apt install keepalived
</span></span></code></pre></div><p>Configure keepalived on the primary. Both virtual IPs go in <code>virtual_ipaddress</code>: the internal resolver address and the authoritative address. An address that is not listed is never brought up on the backup, so it has no failover.</p>
<ul>
<li><code>vrrp_script check_haproxy</code>: <code>killall -0</code> succeeds only while both <code>haproxy</code> and <code>dnsdist</code> run. While it succeeds, the node&rsquo;s priority goes up by <code>weight 2</code>.</li>
<li><code>priority 101</code> (primary) vs <code>100</code> (backup): with both checks passing, 103 beats 102. When the check fails on the primary, 101 loses to 102 and the IPs move.</li>
<li><code>virtual_router_id 53</code>: must match on both nodes and be unique in the network.</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"># /etc/keepalived/keepalived.conf (primary)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">global_defs <span class="o">{</span>
</span></span><span class="line"><span class="cl">    router_id HAPROXY_DNS_1
</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">vrrp_script check_haproxy <span class="o">{</span>
</span></span><span class="line"><span class="cl">    script <span class="s2">&#34;/usr/bin/killall -0 haproxy dnsdist&#34;</span>
</span></span><span class="line"><span class="cl">    interval <span class="m">2</span>
</span></span><span class="line"><span class="cl">    weight <span class="m">2</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">vrrp_instance VI_DNS <span class="o">{</span>
</span></span><span class="line"><span class="cl">    state MASTER
</span></span><span class="line"><span class="cl">    interface eth0
</span></span><span class="line"><span class="cl">    virtual_router_id <span class="m">53</span>
</span></span><span class="line"><span class="cl">    priority <span class="m">101</span>
</span></span><span class="line"><span class="cl">    advert_int <span class="m">1</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    authentication <span class="o">{</span>
</span></span><span class="line"><span class="cl">        auth_type PASS
</span></span><span class="line"><span class="cl">        auth_pass secret123
</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">    virtual_ipaddress <span class="o">{</span>
</span></span><span class="line"><span class="cl">        10.0.0.53/24
</span></span><span class="line"><span class="cl">        <span class="c1"># the authoritative address; add &#34;dev eth1&#34; if it lives on another NIC</span>
</span></span><span class="line"><span class="cl">        203.0.113.53/24
</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">    track_script <span class="o">{</span>
</span></span><span class="line"><span class="cl">        check_haproxy
</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><p>Configure the backup. Only <code>router_id</code>, <code>state</code> and <code>priority</code> differ:</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/keepalived/keepalived.conf (backup)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">global_defs <span class="o">{</span>
</span></span><span class="line"><span class="cl">    router_id HAPROXY_DNS_2
</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">vrrp_script check_haproxy <span class="o">{</span>
</span></span><span class="line"><span class="cl">    script <span class="s2">&#34;/usr/bin/killall -0 haproxy dnsdist&#34;</span>
</span></span><span class="line"><span class="cl">    interval <span class="m">2</span>
</span></span><span class="line"><span class="cl">    weight <span class="m">2</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">vrrp_instance VI_DNS <span class="o">{</span>
</span></span><span class="line"><span class="cl">    state BACKUP
</span></span><span class="line"><span class="cl">    interface eth0
</span></span><span class="line"><span class="cl">    virtual_router_id <span class="m">53</span>
</span></span><span class="line"><span class="cl">    priority <span class="m">100</span>
</span></span><span class="line"><span class="cl">    advert_int <span class="m">1</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    authentication <span class="o">{</span>
</span></span><span class="line"><span class="cl">        auth_type PASS
</span></span><span class="line"><span class="cl">        auth_pass secret123
</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">    virtual_ipaddress <span class="o">{</span>
</span></span><span class="line"><span class="cl">        10.0.0.53/24
</span></span><span class="line"><span class="cl">        <span class="c1"># the authoritative address; add &#34;dev eth1&#34; if it lives on another NIC</span>
</span></span><span class="line"><span class="cl">        203.0.113.53/24
</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">    track_script <span class="o">{</span>
</span></span><span class="line"><span class="cl">        check_haproxy
</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><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 configuration for a production DNS load balancer. It combines the sections above:</p>
<table>
	<thead>
			<tr>
					<th>Frontend</th>
					<th>Address</th>
					<th>Backend</th>
					<th>Rate limit</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>internal_dns_tcp</code></td>
					<td><code>10.0.0.53:53</code></td>
					<td>Internal resolvers, public DNS as <code>backup</code></td>
					<td>30 connections / 10s per client</td>
			</tr>
			<tr>
					<td><code>authoritative_dns_tcp</code></td>
					<td><code>203.0.113.53:53</code></td>
					<td>Authoritative servers, <code>timeout server 30s</code> for zone transfers</td>
					<td>20 connections / 10s per client</td>
			</tr>
			<tr>
					<td><code>dot_frontend</code></td>
					<td><code>*:853</code>, TLS</td>
					<td>Internal resolvers</td>
					<td>None</td>
			</tr>
	</tbody>
</table>
<p>Other settings:</p>
<ul>
<li><code>nbthread 4</code> with <code>cpu-map</code>: four threads, each pinned to one CPU.</li>
<li><code>retries 2</code>: retry a failed connection to a server twice.</li>
<li><code>stats auth admin:changeme</code>: replace this password.</li>
</ul>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy"># /etc/haproxy/haproxy.cfg

global
    log /dev/log local0 info
    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
    
    # Performance
    maxconn 100000
    nbthread 4
    cpu-map auto:1/1-4 0-3
    
    # Security
    tune.ssl.default-dh-param 2048

defaults dns_defaults
    log global
    timeout connect 1s
    timeout client  5s
    timeout server  5s
    default-server inter 3s fall 3 rise 2
    retries 2

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

# ====================
# Internal Resolvers
# ====================

# UDP DNS for internal and external clients is handled by dnsdist (below)

# TCP DNS for internal clients
frontend internal_dns_tcp
    bind 10.0.0.53:53
    mode tcp
    option tcplog
    default_backend internal_resolvers_tcp
    
    # Connection limiting
    stick-table type ip size 50k expire 60s store conn_rate(10s)
    tcp-request connection track-sc0 src
    tcp-request connection reject if { sc0_conn_rate gt 30 }

backend internal_resolvers_tcp
    mode tcp
    balance leastconn
    option tcp-check
    server resolver1 192.168.1.10:53 check
    server resolver2 192.168.1.11:53 check
    server resolver3 192.168.1.12:53 check
    server cloudflare 1.1.1.1:53 check backup
    server quad9      9.9.9.9:53 check backup

# ====================
# Authoritative Servers
# ====================

# TCP DNS for zone transfers and large responses
frontend authoritative_dns_tcp
    bind 203.0.113.53:53
    mode tcp
    option tcplog
    default_backend auth_servers_tcp
    
    # Connection limiting
    stick-table type ip size 100k expire 60s store conn_rate(10s),bytes_out_rate(10s)
    tcp-request connection track-sc0 src
    tcp-request connection reject if { sc0_conn_rate gt 20 }

backend auth_servers_tcp
    mode tcp
    balance roundrobin
    option tcp-check
    timeout server 30s  # Longer timeout for zone transfers
    server auth1 192.168.1.20:53 check
    server auth2 192.168.1.21:53 check
    server auth3 192.168.1.22:53 check

# ====================
# DNS over TLS (DoT)
# ====================

frontend dot_frontend
    bind *:853 ssl crt /etc/haproxy/certs/dns.example.com.pem alpn dns
    mode tcp
    option tcplog
    timeout client 30s
    default_backend internal_resolvers_tcp
    
    # TLS client validation (optional)
    # bind *:853 ssl crt /etc/haproxy/certs/dns.example.com.pem ca-file /etc/haproxy/certs/ca.pem verify optional
</code></pre><p>And the UDP side, with one dnsdist listener per virtual IP. nftables sends each virtual IP to its own port, and the rules pick the pool by port:</p>
<ul>
<li>Port 5354 (authoritative): 50 queries per second per client, then the <code>auth</code> pool.</li>
<li>Port 5353 (internal): 100 queries per second per client, then the <code>internal</code> pool, or <code>fallback</code> when all internal resolvers are down.</li>
<li><code>controlSocket</code> and <code>setKey</code>: the console for <code>dnsdist -c</code>, local only.</li>
</ul>
<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">-- nftables redirects UDP 10.0.0.53:53 to 5353 and UDP 203.0.113.53:53 to 5354</span>
</span></span><span class="line"><span class="cl"><span class="n">addLocal</span><span class="p">(</span><span class="s1">&#39;0.0.0.0:5353&#39;</span><span class="p">)</span>   <span class="c1">-- internal resolvers</span>
</span></span><span class="line"><span class="cl"><span class="n">addLocal</span><span class="p">(</span><span class="s1">&#39;0.0.0.0:5354&#39;</span><span class="p">)</span>   <span class="c1">-- authoritative servers</span>
</span></span><span class="line"><span class="cl"><span class="n">setACL</span><span class="p">({</span> <span class="s1">&#39;0.0.0.0/0&#39;</span><span class="p">,</span> <span class="s1">&#39;::/0&#39;</span> <span class="p">})</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">-- Internal resolvers, public DNS as fallback</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="s1">&#39;192.168.1.10:53&#39;</span><span class="p">,</span> <span class="n">name</span> <span class="o">=</span> <span class="s1">&#39;resolver1&#39;</span><span class="p">,</span> <span class="n">pool</span> <span class="o">=</span> <span class="s1">&#39;internal&#39;</span> <span class="p">})</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="s1">&#39;192.168.1.11:53&#39;</span><span class="p">,</span> <span class="n">name</span> <span class="o">=</span> <span class="s1">&#39;resolver2&#39;</span><span class="p">,</span> <span class="n">pool</span> <span class="o">=</span> <span class="s1">&#39;internal&#39;</span> <span class="p">})</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="s1">&#39;192.168.1.12:53&#39;</span><span class="p">,</span> <span class="n">name</span> <span class="o">=</span> <span class="s1">&#39;resolver3&#39;</span><span class="p">,</span> <span class="n">pool</span> <span class="o">=</span> <span class="s1">&#39;internal&#39;</span> <span class="p">})</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="s1">&#39;1.1.1.1:53&#39;</span><span class="p">,</span> <span class="n">name</span> <span class="o">=</span> <span class="s1">&#39;cloudflare&#39;</span><span class="p">,</span> <span class="n">pool</span> <span class="o">=</span> <span class="s1">&#39;fallback&#39;</span> <span class="p">})</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="s1">&#39;9.9.9.9:53&#39;</span><span class="p">,</span> <span class="n">name</span> <span class="o">=</span> <span class="s1">&#39;quad9&#39;</span><span class="p">,</span> <span class="n">pool</span> <span class="o">=</span> <span class="s1">&#39;fallback&#39;</span> <span class="p">})</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">-- Authoritative servers</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="s1">&#39;192.168.1.20:53&#39;</span><span class="p">,</span> <span class="n">name</span> <span class="o">=</span> <span class="s1">&#39;auth1&#39;</span><span class="p">,</span> <span class="n">pool</span> <span class="o">=</span> <span class="s1">&#39;auth&#39;</span> <span class="p">})</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="s1">&#39;192.168.1.21:53&#39;</span><span class="p">,</span> <span class="n">name</span> <span class="o">=</span> <span class="s1">&#39;auth2&#39;</span><span class="p">,</span> <span class="n">pool</span> <span class="o">=</span> <span class="s1">&#39;auth&#39;</span> <span class="p">})</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="s1">&#39;192.168.1.22:53&#39;</span><span class="p">,</span> <span class="n">name</span> <span class="o">=</span> <span class="s1">&#39;auth3&#39;</span><span class="p">,</span> <span class="n">pool</span> <span class="o">=</span> <span class="s1">&#39;auth&#39;</span> <span class="p">})</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">setServerPolicy</span><span class="p">(</span><span class="n">roundrobin</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">-- Authoritative listener: strict rate limiting, authoritative servers only</span>
</span></span><span class="line"><span class="cl"><span class="n">addAction</span><span class="p">(</span><span class="n">AndRule</span><span class="p">({</span> <span class="n">DSTPortRule</span><span class="p">(</span><span class="mi">5354</span><span class="p">),</span> <span class="n">MaxQPSIPRule</span><span class="p">(</span><span class="mi">50</span><span class="p">)</span> <span class="p">}),</span> <span class="n">DropAction</span><span class="p">())</span>
</span></span><span class="line"><span class="cl"><span class="n">addAction</span><span class="p">(</span><span class="n">DSTPortRule</span><span class="p">(</span><span class="mi">5354</span><span class="p">),</span> <span class="n">PoolAction</span><span class="p">(</span><span class="s1">&#39;auth&#39;</span><span class="p">))</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">-- Internal listener: rate limiting, resolvers with public fallback</span>
</span></span><span class="line"><span class="cl"><span class="n">addAction</span><span class="p">(</span><span class="n">MaxQPSIPRule</span><span class="p">(</span><span class="mi">100</span><span class="p">),</span> <span class="n">DropAction</span><span class="p">())</span>
</span></span><span class="line"><span class="cl"><span class="n">addAction</span><span class="p">(</span><span class="n">PoolAvailableRule</span><span class="p">(</span><span class="s1">&#39;internal&#39;</span><span class="p">),</span> <span class="n">PoolAction</span><span class="p">(</span><span class="s1">&#39;internal&#39;</span><span class="p">))</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">PoolAction</span><span class="p">(</span><span class="s1">&#39;fallback&#39;</span><span class="p">))</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">-- Console for dnsdist -c (generate a key with: head -c 32 /dev/urandom | base64)</span>
</span></span><span class="line"><span class="cl"><span class="n">controlSocket</span><span class="p">(</span><span class="s1">&#39;127.0.0.1:5199&#39;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="n">setKey</span><span class="p">(</span><span class="s1">&#39;replace-with-your-base64-key&#39;</span><span class="p">)</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="c1"># /etc/nftables.conf (add below the existing tables)</span>
</span></span><span class="line"><span class="cl">table ip dns_udp <span class="o">{</span>
</span></span><span class="line"><span class="cl">    chain prerouting <span class="o">{</span>
</span></span><span class="line"><span class="cl">        <span class="nb">type</span> nat hook prerouting priority dstnat<span class="p">;</span> policy accept<span class="p">;</span>
</span></span><span class="line"><span class="cl">        ip daddr 10.0.0.53 udp dport <span class="m">53</span> redirect to :5353
</span></span><span class="line"><span class="cl">        ip daddr 203.0.113.53 udp dport <span class="m">53</span> redirect to :5354
</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><h2 id="monitoring-and-logging">Monitoring and Logging <a class="anchor" data-pagefind-ignore href="#monitoring-and-logging" aria-label="Link to this section">#</a></h2>
<h3 id="dns-query-logging">DNS Query Logging <a class="anchor" data-pagefind-ignore href="#dns-query-logging" aria-label="Link to this section">#</a></h3>
<p><code>option tcplog</code> logs one line per connection, not per query. The custom <code>log-format</code> adds the client, the chosen server, the timers (<code>%Tw/%Tc/%Tt</code>), bytes sent and the connection counts.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend dns_tcp
    bind *:53
    mode tcp
    option tcplog
    log-format &#34;%ci:%cp [%t] %ft %b/%s %Tw/%Tc/%Tt %B %ts %ac/%fc/%bc/%sc/%rc&#34;
    default_backend dns_servers
</code></pre><h3 id="prometheus-metrics">Prometheus Metrics <a class="anchor" data-pagefind-ignore href="#prometheus-metrics" aria-label="Link to this section">#</a></h3>
<p>Enable the built-in Prometheus exporter:</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">listen stats
    bind *:8404
    mode http
    http-request use-service prometheus-exporter if { path /metrics }
</code></pre><p>Key metrics to monitor:</p>
<ul>
<li><code>haproxy_server_status</code>: Backend server health</li>
<li><code>haproxy_frontend_current_sessions</code>: Active connections</li>
<li><code>haproxy_frontend_bytes_in_total</code>: Incoming traffic</li>
<li><code>haproxy_frontend_bytes_out_total</code>: Outgoing traffic (watch for amplification)</li>
</ul>
<p>These cover HAProxy, so TCP and DoT only. dnsdist handles most queries (UDP); check it with <code>showServers()</code> (below).</p>
<h2 id="testing-your-configuration">Testing Your Configuration <a class="anchor" data-pagefind-ignore href="#testing-your-configuration" aria-label="Link to this section">#</a></h2>
<h3 id="validate-configuration">Validate Configuration <a class="anchor" data-pagefind-ignore href="#validate-configuration" aria-label="Link to this section">#</a></h3>
<p>Check the syntax before every reload.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">haproxy -c -f /etc/haproxy/haproxy.cfg
</span></span></code></pre></div><h3 id="test-dns-resolution">Test DNS Resolution <a class="anchor" data-pagefind-ignore href="#test-dns-resolution" aria-label="Link to this section">#</a></h3>
<p>Query the virtual IP over both protocols, then each server directly. If a direct query works but the virtual IP does not, the problem is in the load balancer.</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"># UDP query (dnsdist)</span>
</span></span><span class="line"><span class="cl">dig @10.0.0.53 google.com A
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># TCP query (HAProxy)</span>
</span></span><span class="line"><span class="cl">dig @10.0.0.53 +tcp google.com A
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test all servers</span>
</span></span><span class="line"><span class="cl"><span class="k">for</span> server in 192.168.1.10 192.168.1.11 192.168.1.12<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;Testing </span><span class="nv">$server</span><span class="s2">:&#34;</span>
</span></span><span class="line"><span class="cl">    dig @<span class="nv">$server</span> +short google.com A
</span></span><span class="line"><span class="cl"><span class="k">done</span>
</span></span></code></pre></div><h3 id="load-testing">Load Testing <a class="anchor" data-pagefind-ignore href="#load-testing" aria-label="Link to this section">#</a></h3>
<p><code>dnsperf</code> sends queries from a file: <code>-c 100</code> clients, at most <code>-Q 10000</code> queries per second. Run it once per protocol. Keep the rate limits in mind: from one test machine you hit them quickly.</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 dnsperf</span>
</span></span><span class="line"><span class="cl">apt install dnsperf
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create query file</span>
</span></span><span class="line"><span class="cl">cat &gt; queries.txt <span class="s">&lt;&lt; EOF
</span></span></span><span class="line"><span class="cl"><span class="s">google.com A
</span></span></span><span class="line"><span class="cl"><span class="s">example.com A
</span></span></span><span class="line"><span class="cl"><span class="s">github.com A
</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"># Run load test (UDP, through dnsdist)</span>
</span></span><span class="line"><span class="cl">dnsperf -s 10.0.0.53 -d queries.txt -c <span class="m">100</span> -Q <span class="m">10000</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># The same over TCP, through HAProxy</span>
</span></span><span class="line"><span class="cl">dnsperf -m tcp -s 10.0.0.53 -d queries.txt -c <span class="m">100</span> -Q <span class="m">10000</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-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>Check</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>UDP not working</td>
					<td>UDP goes through dnsdist, not HAProxy. Check that dnsdist listens (<code>ss -ulpn | grep 5353</code>), that the nftables redirect is loaded (<code>nft list table ip dns_udp</code>), that <code>setACL()</code> allows your clients, and that <code>showServers()</code> lists the backends as up.</td>
			</tr>
			<tr>
					<td>Health checks failing</td>
					<td>Verify DNS servers are responding, check firewall rules. With the DNS query check: does <code>health.local</code> exist on every server?</td>
			</tr>
			<tr>
					<td>High latency</td>
					<td>Check <code>timeout</code> settings and server response times.</td>
			</tr>
			<tr>
					<td>Connection refused</td>
					<td>Verify HAProxy is binding correctly (<code>ss -tulpn | grep 53</code>).</td>
			</tr>
			<tr>
					<td>Other firewall rules gone</td>
					<td><code>flush ruleset</code> in <code>/etc/nftables.conf</code> (see the warning above).</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>
<p>The admin socket shows what HAProxy sees; <code>dnsdist -c</code> does the same for the UDP side.</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 HAProxy status</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;show info&#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"># Check backend servers</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;show servers state&#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"># Check statistics</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;show stat&#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"># Watch connections in real-time</span>
</span></span><span class="line"><span class="cl">watch -n <span class="m">1</span> <span class="s1">&#39;echo &#34;show stat&#34; | socat stdio /run/haproxy/admin.sock | cut -d, -f1,2,5,18&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># dnsdist (UDP) backends and their state</span>
</span></span><span class="line"><span class="cl">dnsdist -c -e <span class="s1">&#39;showServers()&#39;</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>Change the example secrets</strong>: <code>auth_pass secret123</code> in keepalived, <code>stats auth admin:changeme</code> in HAProxy, and the dnsdist console key. VRRP <code>PASS</code> authentication is sent in plain text; it only guards against mistakes.</li>
<li><strong>Keep resolvers internal.</strong> The production dnsdist config sets <code>setACL({ '0.0.0.0/0', '::/0' })</code> for the authoritative side, and that ACL also covers the internal listener. Make sure only internal clients can reach <code>10.0.0.53</code> and port 5353, or you run an open resolver.</li>
<li><strong>Keep the rate limits.</strong> They are what stops the load balancer from being used for amplification attacks.</li>
<li><strong>Avoid external checks where you can.</strong> <code>insecure-fork-wanted</code> lifts a safety guard in HAProxy.</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-dns-lb" rel="noopener">pderuiter/blog-haproxy-dns-lb</a>. It creates two load balancer VMs on Proxmox and configures HAProxy for TCP and DoT, dnsdist with the nftables redirect for UDP, and keepalived for the virtual IPs, as in the complete production configuration from this post; 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: <a href="https://blog.bsdserver.nl/haproxy-with-lets-encrypt-automated-https-certificate-management/">HAProxy with Let&rsquo;s Encrypt</a> for automatic HTTPS certificate management.</p>
<h2 id="summary">Summary <a class="anchor" data-pagefind-ignore href="#summary" aria-label="Link to this section">#</a></h2>
<ul>
<li>HAProxy cannot proxy UDP (also not in 3.4): use dnsdist for DNS over UDP</li>
<li>Cover both UDP (dnsdist) and TCP (HAProxy) on the same address for complete DNS coverage</li>
<li>Implement proper health checks for DNS servers</li>
<li>Use rate limiting to protect against abuse</li>
<li>Deploy keepalived for HAProxy and dnsdist high availability</li>
</ul>
]]></content:encoded></item><item><title>HAProxy TCP Load Balancing: A Complete Guide to Layer 4 Load Balancing</title><link>https://blog.bsdserver.nl/haproxy-tcp-load-balancing-a-complete-guide-to-layer-4-load-balancing/</link><guid isPermaLink="false">693b721e79eb54000160a5dc</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:38:38 +0000</pubDate><description>HAProxy is one of the most powerful and reliable load balancers available.</description><category>HAProxy</category><category>Load balancing</category><category>TCP</category><category>High availability</category><category>Networking</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/haproxy-tcp-loadbalancing.png" medium="image"/><content:encoded><![CDATA[<p>HAProxy is one of the most powerful and reliable load balancers available. It is best known for HTTP, but databases, Redis, message queues and TLS services speak their own protocols over TCP, and they need load balancing and failover too.</p>
<p>This guide covers HAProxy in TCP mode: algorithms, protocol-aware health checks, connection limits, failover patterns, TLS passthrough, client IP preservation and logging, ending with a complete PostgreSQL and Redis configuration.</p>
<h2 id="why-tcp-load-balancing">Why TCP Load Balancing? <a class="anchor" data-pagefind-ignore href="#why-tcp-load-balancing" aria-label="Link to this section">#</a></h2>
<p>Layer 4 load balancing works at the transport layer: it routes on IP addresses and ports and forwards the bytes without reading them.</p>
<ul>
<li><strong>Protocol agnostic</strong>: Works with any TCP-based protocol (databases, message queues, custom protocols)</li>
<li><strong>Lower latency</strong>: No content inspection means faster routing decisions</li>
<li><strong>TLS passthrough</strong>: End-to-end encryption without termination at the load balancer</li>
<li><strong>Simplicity</strong>: Fewer moving parts compared to Layer 7 configuration</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 non-HTTP protocols, and for HTTPS when the backends must terminate TLS themselves.</li>
<li><strong>Skip it</strong> for plain HTTP(S) services where you want path routing, header changes or HTTP-level logs: use <code>mode http</code>.</li>
</ul>
<table>
	<thead>
			<tr>
					<th></th>
					<th><code>mode tcp</code> (Layer 4)</th>
					<th><code>mode http</code> (Layer 7)</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Routes on</td>
					<td>IP, port, TLS SNI</td>
					<td>Host, path, headers, cookies</td>
			</tr>
			<tr>
					<td>Sees content</td>
					<td>No</td>
					<td>Yes</td>
			</tr>
			<tr>
					<td>Protocols</td>
					<td>Any TCP</td>
					<td>HTTP/1.x, HTTP/2, HTTP/3</td>
			</tr>
			<tr>
					<td>TLS</td>
					<td>Passthrough or termination</td>
					<td>Termination</td>
			</tr>
	</tbody>
</table>
<h2 id="architecture-overview">Architecture Overview <a class="anchor" data-pagefind-ignore href="#architecture-overview" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Frontend</td>
					<td>HAProxy</td>
					<td>Listens on a port (<code>bind *:5432</code>) and picks a backend.</td>
			</tr>
			<tr>
					<td>Backend</td>
					<td>HAProxy</td>
					<td>Holds the server list, the algorithm and the health check.</td>
			</tr>
			<tr>
					<td>Servers</td>
					<td>Database, Redis or app hosts</td>
					<td>Receive the forwarded TCP connections.</td>
			</tr>
			<tr>
					<td>Stats socket</td>
					<td>HAProxy</td>
					<td>Runtime control: drain, disable, show state.</td>
			</tr>
	</tbody>
</table>
<p>The flow: client connects to HAProxy → frontend picks a backend → algorithm picks a healthy server → HAProxy opens a connection to it and copies bytes both ways until one side closes.</p>
<h2 id="installation">Installation <a class="anchor" data-pagefind-ignore href="#installation" aria-label="Link to this section">#</a></h2>
<p>On Debian/Ubuntu, use the official HAProxy packages from <a href="https://haproxy.debian.net" rel="noopener">haproxy.debian.net</a> instead of the distribution package, which lags several branches behind:</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></code></pre></div><p>On RHEL/CentOS there is no official HAProxy package repository, so you get the distribution version:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">yum install haproxy
</span></span><span class="line"><span class="cl"><span class="c1"># RHEL/Rocky/Alma 9 AppStream ships the 2.8 LTS branch; check what you got</span>
</span></span><span class="line"><span class="cl">haproxy -v
</span></span></code></pre></div><p>The RHEL unit file does not create <code>/run/haproxy</code>, so the <code>stats socket /run/haproxy/admin.sock</code> line used throughout this post stops HAProxy from starting. Let systemd create the directory:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><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><h2 id="basic-tcp-load-balancer-configuration">Basic TCP Load Balancer Configuration <a class="anchor" data-pagefind-ignore href="#basic-tcp-load-balancer-configuration" aria-label="Link to this section">#</a></h2>
<p>A minimal load balancer for three MySQL servers. What matters for TCP:</p>
<ul>
<li><code>mode tcp</code> and <code>option tcplog</code> in <code>defaults</code>: every proxy works at Layer 4 and logs connections, not requests.</li>
<li><code>timeout client</code> / <code>timeout server</code>: idle time before HAProxy closes the connection. Too low cuts off idle database sessions.</li>
<li><code>retries 3</code>: connection attempts to a server before giving up.</li>
<li><code>option mysql-check</code>: a health check that logs in to MySQL instead of only opening the port.</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
    stats timeout 30s
    user haproxy
    group haproxy
    daemon
    
    # Performance tuning
    maxconn 50000
    tune.ssl.default-dh-param 2048

defaults
    log     global
    mode    tcp
    option  tcplog
    option  dontlognull
    timeout connect 10s
    timeout client  30s
    timeout server  30s
    retries 3

frontend mysql_frontend
    bind *:3306
    default_backend mysql_servers

backend mysql_servers
    balance roundrobin
    option mysql-check user haproxy
    server mysql1 192.168.1.10:3306 check
    server mysql2 192.168.1.11:3306 check
    server mysql3 192.168.1.12:3306 check
</code></pre><h2 id="load-balancing-algorithms">Load Balancing Algorithms <a class="anchor" data-pagefind-ignore href="#load-balancing-algorithms" aria-label="Link to this section">#</a></h2>
<p>The algorithm decides which server gets the next connection.</p>
<table>
	<thead>
			<tr>
					<th>Algorithm</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>roundrobin</code></td>
					<td>Short connections of similar cost; supports weights</td>
			</tr>
			<tr>
					<td><code>leastconn</code></td>
					<td>Long-lived connections such as database sessions</td>
			</tr>
			<tr>
					<td><code>source</code></td>
					<td>Clients that must stay on the same server</td>
			</tr>
			<tr>
					<td><code>first</code></td>
					<td>Filling servers one by one, for example so spare servers can sleep</td>
			</tr>
	</tbody>
</table>
<h3 id="round-robin">Round Robin <a class="anchor" data-pagefind-ignore href="#round-robin" aria-label="Link to this section">#</a></h3>
<p>Distributes connections in turn, in proportion to <code>weight</code>:</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">backend servers
    balance roundrobin
    server s1 192.168.1.10:5432 check weight 1
    server s2 192.168.1.11:5432 check weight 2  # Gets 2x traffic
    server s3 192.168.1.12:5432 check weight 1
</code></pre><h3 id="least-connections">Least Connections <a class="anchor" data-pagefind-ignore href="#least-connections" aria-label="Link to this section">#</a></h3>
<p>Sends traffic to the server with fewest active connections:</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">backend servers
    balance leastconn
    server s1 192.168.1.10:5432 check
    server s2 192.168.1.11:5432 check
    server s3 192.168.1.12:5432 check
</code></pre><h3 id="source-ip-hash">Source IP Hash <a class="anchor" data-pagefind-ignore href="#source-ip-hash" aria-label="Link to this section">#</a></h3>
<p>Ensures the same client always connects to the same server (session persistence). <code>hash-type consistent</code> moves only a few clients when a server is added or removed.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">backend servers
    balance source
    hash-type consistent
    server s1 192.168.1.10:5432 check
    server s2 192.168.1.11:5432 check
    server s3 192.168.1.12:5432 check
</code></pre><h3 id="first-available">First Available <a class="anchor" data-pagefind-ignore href="#first-available" aria-label="Link to this section">#</a></h3>
<p>Uses the first server with available connection slots. Requires <code>maxconn</code> on the servers: the next server only gets traffic when the first is full.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">backend servers
    balance first
    server s1 192.168.1.10:5432 check maxconn 100
    server s2 192.168.1.11:5432 check maxconn 100
</code></pre><h2 id="health-checks">Health Checks <a class="anchor" data-pagefind-ignore href="#health-checks" aria-label="Link to this section">#</a></h2>
<p>HAProxy only sends traffic to servers that pass their check. An open port is not a working service, so use a protocol check where one exists.</p>
<table>
	<thead>
			<tr>
					<th>Check</th>
					<th>Proves</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>option tcp-check</code> (no steps)</td>
					<td>The port accepts connections</td>
			</tr>
			<tr>
					<td><code>mysql-check</code>, <code>pgsql-check</code></td>
					<td>The database answers its handshake</td>
			</tr>
			<tr>
					<td><code>tcp-check send</code> / <code>expect</code></td>
					<td>The service gives the right answer to a request you define</td>
			</tr>
	</tbody>
</table>
<h3 id="basic-tcp-check">Basic TCP Check <a class="anchor" data-pagefind-ignore href="#basic-tcp-check" aria-label="Link to this section">#</a></h3>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">backend servers
    option tcp-check
    server s1 192.168.1.10:5432 check
</code></pre><h3 id="protocol-specific-health-checks">Protocol-Specific Health Checks <a class="anchor" data-pagefind-ignore href="#protocol-specific-health-checks" aria-label="Link to this section">#</a></h3>
<h4 id="mysqlmariadb">MySQL/MariaDB <a class="anchor" data-pagefind-ignore href="#mysqlmariadb" aria-label="Link to this section">#</a></h4>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">backend mysql_servers
    option mysql-check user haproxy
    server mysql1 192.168.1.10:3306 check
</code></pre><p>The check logs in as <code>haproxy</code> without a password. Create the HAProxy user in MySQL:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sql" data-lang="sql"><span class="line"><span class="cl"><span class="k">CREATE</span><span class="w"> </span><span class="k">USER</span><span class="w"> </span><span class="s1">&#39;haproxy&#39;</span><span class="o">@</span><span class="s1">&#39;%&#39;</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="n">FLUSH</span><span class="w"> </span><span class="k">PRIVILEGES</span><span class="p">;</span><span class="w">
</span></span></span></code></pre></div><h4 id="postgresql">PostgreSQL <a class="anchor" data-pagefind-ignore href="#postgresql" aria-label="Link to this section">#</a></h4>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">backend postgres_servers
    option pgsql-check user haproxy
    server pg1 192.168.1.10:5432 check
</code></pre><h4 id="redis">Redis <a class="anchor" data-pagefind-ignore href="#redis" aria-label="Link to this section">#</a></h4>
<p>Sends <code>PING</code> and expects <code>+PONG</code>.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">backend redis_servers
    option tcp-check
    tcp-check connect
    tcp-check send PING\r\n
    tcp-check expect string +PONG
    server redis1 192.168.1.10:6379 check
</code></pre><h4 id="custom-tcp-check">Custom TCP Check <a class="anchor" data-pagefind-ignore href="#custom-tcp-check" aria-label="Link to this section">#</a></h4>
<p>Sends a raw HTTP request and expects a <code>200</code> status line. <code>tcp-check connect port</code> lets the check use another port than the traffic, for a health endpoint on a separate port.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">backend custom_servers
    option tcp-check
    tcp-check connect port 8080
    tcp-check send &#34;GET /health HTTP/1.1\r\nHost: localhost\r\n\r\n&#34;
    tcp-check expect rstring ^HTTP/1\.[01]\ 200
    server app1 192.168.1.10:8080 check
</code></pre><h3 id="health-check-parameters">Health Check Parameters <a class="anchor" data-pagefind-ignore href="#health-check-parameters" aria-label="Link to this section">#</a></h3>
<p><code>default-server</code> sets the values for all servers in the backend; a value on a <code>server</code> line overrides it.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">backend servers
    default-server inter 3s fall 3 rise 2
    server s1 192.168.1.10:5432 check
    server s2 192.168.1.11:5432 check inter 5s fall 2 rise 3
</code></pre><ul>
<li><code>inter</code>: Interval between checks (default: 2s)</li>
<li><code>fall</code>: Number of failed checks before marking server down</li>
<li><code>rise</code>: Number of successful checks before marking server up</li>
</ul>
<h2 id="connection-management">Connection Management <a class="anchor" data-pagefind-ignore href="#connection-management" aria-label="Link to this section">#</a></h2>
<p>Limits protect the backends: HAProxy queues or rejects connections instead of overloading a server.</p>
<h3 id="maximum-connections">Maximum Connections <a class="anchor" data-pagefind-ignore href="#maximum-connections" aria-label="Link to this section">#</a></h3>
<p><code>maxconn</code> works at three levels:</p>
<ul>
<li><code>global</code>: the whole process. Above it, HAProxy stops accepting.</li>
<li><code>frontend</code>: per listener.</li>
<li><code>server</code>: per backend server. Extra connections wait in the backend queue.</li>
</ul>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">global
    maxconn 50000

frontend db_frontend
    bind *:5432
    maxconn 10000
    default_backend db_servers

backend db_servers
    server db1 192.168.1.10:5432 check maxconn 500
    server db2 192.168.1.11:5432 check maxconn 500
</code></pre><h3 id="connection-queuing">Connection Queuing <a class="anchor" data-pagefind-ignore href="#connection-queuing" aria-label="Link to this section">#</a></h3>
<p><code>maxqueue 50</code> caps the queue for a server; beyond that, connections go to another server or fail instead of waiting.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">backend servers
    fullconn 1000
    server s1 192.168.1.10:5432 check maxconn 100 maxqueue 50
</code></pre><h3 id="connection-timeouts">Connection Timeouts <a class="anchor" data-pagefind-ignore href="#connection-timeouts" aria-label="Link to this section">#</a></h3>
<p>Each timeout covers one phase of a connection; the comments say which.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">defaults
    timeout connect 5s      # Time to establish connection to server
    timeout client  60s     # Inactivity timeout on client side
    timeout server  60s     # Inactivity timeout on server side
    timeout tunnel  1h      # Timeout for tunneled connections (WebSocket, etc.)
    timeout client-fin 30s  # Timeout for client FIN
    timeout server-fin 30s  # Timeout for server FIN
</code></pre><p>Database clients and pools keep connections open and idle. Raise the client and server timeouts, or HAProxy closes them:</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">defaults
    timeout client  3600s
    timeout server  3600s
</code></pre><h2 id="high-availability-patterns">High Availability Patterns <a class="anchor" data-pagefind-ignore href="#high-availability-patterns" aria-label="Link to this section">#</a></h2>
<h3 id="active-passive-with-backup-servers">Active-Passive with Backup Servers <a class="anchor" data-pagefind-ignore href="#active-passive-with-backup-servers" aria-label="Link to this section">#</a></h3>
<p>Servers marked <code>backup</code> only get traffic when all normal servers are down.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">backend db_servers
    balance roundrobin
    server primary1 192.168.1.10:5432 check
    server primary2 192.168.1.11:5432 check
    server backup1  192.168.1.20:5432 check backup
    server backup2  192.168.1.21:5432 check backup
</code></pre><h3 id="readwrite-splitting">Read/Write Splitting <a class="anchor" data-pagefind-ignore href="#readwrite-splitting" aria-label="Link to this section">#</a></h3>
<p>For database clusters with a primary and replicas. One frontend listens on two ports; <code>dst_port</code> sends writes to the primary and reads to the replicas. The application chooses the port.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend mysql_frontend
    bind *:3306
    bind *:3307
    
    # Port 3306 -&gt; Write (Primary)
    # Port 3307 -&gt; Read (Replicas)
    use_backend mysql_write if { dst_port 3306 }
    use_backend mysql_read if { dst_port 3307 }

backend mysql_write
    option mysql-check user haproxy
    server primary 192.168.1.10:3306 check

backend mysql_read
    balance leastconn
    option mysql-check user haproxy
    server replica1 192.168.1.11:3306 check
    server replica2 192.168.1.12:3306 check
    server primary  192.168.1.10:3306 check backup  # Fallback to primary
</code></pre><h3 id="graceful-server-maintenance">Graceful Server Maintenance <a class="anchor" data-pagefind-ignore href="#graceful-server-maintenance" aria-label="Link to this section">#</a></h3>
<p>Take a server out without cutting active connections. <code>weight 0</code> in the configuration stops new connections; the stats socket does the same at runtime without a reload.</p>
<table>
	<thead>
			<tr>
					<th>Command</th>
					<th>Effect</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>disable server</code></td>
					<td>Maintenance mode: no new connections, existing ones continue</td>
			</tr>
			<tr>
					<td><code>set server ... state drain</code></td>
					<td>No new load-balanced connections, health checks keep running</td>
			</tr>
			<tr>
					<td><code>enable server</code></td>
					<td>Back in rotation</td>
			</tr>
	</tbody>
</table>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">backend servers
    server s1 192.168.1.10:5432 check
    server s2 192.168.1.11:5432 check weight 0  # No new connections (drain)
</code></pre><p>Use the stats socket to manage servers dynamically:</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"># Disable a server (existing connections preserved)</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;disable server servers/s1&#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"># Set server to drain mode</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;set server servers/s1 state drain&#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"># Re-enable a server</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;enable server servers/s1&#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"># Check server status</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;show servers state&#34;</span> <span class="p">|</span> socat stdio /run/haproxy/admin.sock
</span></span></code></pre></div><h2 id="tls-passthrough">TLS Passthrough <a class="anchor" data-pagefind-ignore href="#tls-passthrough" aria-label="Link to this section">#</a></h2>
<p>For end-to-end encryption without terminating TLS at the load balancer. HAProxy forwards the encrypted stream; certificates live on the backends.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend tls_frontend
    bind *:443
    mode tcp
    option tcplog
    default_backend tls_servers

backend tls_servers
    mode tcp
    balance roundrobin
    server s1 192.168.1.10:443 check
    server s2 192.168.1.11:443 check
</code></pre><h3 id="sni-based-routing">SNI-Based Routing <a class="anchor" data-pagefind-ignore href="#sni-based-routing" aria-label="Link to this section">#</a></h3>
<p>Route to different backends based on the TLS SNI header, the hostname the client sends unencrypted in its TLS hello.</p>
<ul>
<li><code>tcp-request inspect-delay 5s</code>: wait up to 5 seconds for the hello before deciding.</li>
<li><code>req_ssl_hello_type 1</code>: accept once a ClientHello arrived.</li>
<li><code>req_ssl_sni</code>: the requested hostname.</li>
</ul>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend tls_frontend
    bind *:443
    mode tcp
    tcp-request inspect-delay 5s
    tcp-request content accept if { req_ssl_hello_type 1 }
    
    use_backend app1_servers if { req_ssl_sni -i app1.example.com }
    use_backend app2_servers if { req_ssl_sni -i app2.example.com }
    default_backend default_servers

backend app1_servers
    mode tcp
    server app1 192.168.1.10:443 check

backend app2_servers
    mode tcp
    server app2 192.168.1.20:443 check

backend default_servers
    mode tcp
    server default1 192.168.1.30:443 check
</code></pre><h2 id="client-ip-preservation">Client IP Preservation <a class="anchor" data-pagefind-ignore href="#client-ip-preservation" aria-label="Link to this section">#</a></h2>
<h3 id="proxy-protocol">PROXY Protocol <a class="anchor" data-pagefind-ignore href="#proxy-protocol" aria-label="Link to this section">#</a></h3>
<p>In TCP mode the backend sees HAProxy&rsquo;s IP, not the client&rsquo;s, and there are no headers to add <code>X-Forwarded-For</code> to. The PROXY protocol passes client information through TCP load balancers by sending a short header before the data:</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend tcp_frontend
    bind *:5432
    default_backend tcp_servers

backend tcp_servers
    server s1 192.168.1.10:5432 check send-proxy-v2
</code></pre><p>The backend server must support PROXY protocol, or it reads the header as garbage and drops the connection. For HAProxy as the backend:</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend backend_frontend
    bind *:5432 accept-proxy
    # ...
</code></pre><h2 id="logging">Logging <a class="anchor" data-pagefind-ignore href="#logging" aria-label="Link to this section">#</a></h2>
<h3 id="tcp-specific-logging">TCP-Specific Logging <a class="anchor" data-pagefind-ignore href="#tcp-specific-logging" aria-label="Link to this section">#</a></h3>
<p><code>option tcplog</code> logs one line per connection. The custom <code>log-format</code> adds timings and connection counts.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">global
    log 127.0.0.1:514 local0 info

defaults
    mode tcp
    option tcplog
    log global

# Custom TCP log format
frontend tcp_frontend
    bind *:5432
    log-format &#34;%ci:%cp [%t] %ft %b/%s %Tw/%Tc/%Tt %B %ts %ac/%fc/%bc/%sc/%rc %sq/%bq&#34;
</code></pre><p>Log format variables for TCP:</p>
<ul>
<li><code>%ci</code>: Client IP</li>
<li><code>%cp</code>: Client port</li>
<li><code>%ft</code>: Frontend name</li>
<li><code>%b</code>: Backend name</li>
<li><code>%s</code>: Server name</li>
<li><code>%Tw</code>: Time waiting in queue (ms)</li>
<li><code>%Tc</code>: Time to connect to server (ms)</li>
<li><code>%Tt</code>: Total time (ms)</li>
<li><code>%B</code>: Bytes read from server</li>
<li><code>%ts</code>: Termination state</li>
</ul>
<p>HAProxy sends logs to syslog on UDP 514. Configure rsyslog to receive them and write <code>local0</code> to a 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"># /etc/rsyslog.d/haproxy.conf</span>
</span></span><span class="line"><span class="cl"><span class="nv">$ModLoad</span> imudp
</span></span><span class="line"><span class="cl"><span class="nv">$UDPServerRun</span> <span class="m">514</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">local0.* /var/log/haproxy.log
</span></span></code></pre></div><h2 id="statistics-and-monitoring">Statistics and Monitoring <a class="anchor" data-pagefind-ignore href="#statistics-and-monitoring" aria-label="Link to this section">#</a></h2>
<p>The stats page is HTTP even when all your proxies are TCP, so it sets <code>mode http</code> itself.</p>
<h3 id="stats-page">Stats Page <a class="anchor" data-pagefind-ignore href="#stats-page" aria-label="Link to this section">#</a></h3>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend stats
    bind *:8404
    mode http
    stats enable
    stats uri /stats
    stats refresh 10s
    stats admin if LOCALHOST
</code></pre><h3 id="prometheus-metrics">Prometheus Metrics <a class="anchor" data-pagefind-ignore href="#prometheus-metrics" aria-label="Link to this section">#</a></h3>
<p>See <a href="https://blog.bsdserver.nl/haproxy-monitoring-with-prometheus-complete-observability-guide/">HAProxy Monitoring with Prometheus</a> for scraping and alerting.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend stats
    bind *:8404
    mode http
    http-request use-service prometheus-exporter if { path /metrics }
</code></pre><h2 id="complete-production-example">Complete Production Example <a class="anchor" data-pagefind-ignore href="#complete-production-example" aria-label="Link to this section">#</a></h2>
<p>A complete configuration for a PostgreSQL cluster and Redis:</p>
<table>
	<thead>
			<tr>
					<th>Frontend</th>
					<th>Port</th>
					<th>Backend</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>pg_write</code></td>
					<td>5432</td>
					<td>Primary, standby as backup; over 5000 connections are rejected</td>
			</tr>
			<tr>
					<td><code>pg_read</code></td>
					<td>5433</td>
					<td>Standbys with <code>leastconn</code>, primary as backup</td>
			</tr>
			<tr>
					<td><code>redis</code></td>
					<td>6379</td>
					<td>Only the server reporting <code>role:master</code> passes the check</td>
			</tr>
			<tr>
					<td><code>stats</code></td>
					<td>8404</td>
					<td>Stats page and <code>/metrics</code></td>
			</tr>
	</tbody>
</table>
<p>Settings worth knowing:</p>
<ul>
<li><code>option redispatch</code>: retry on another server if the chosen one fails.</li>
<li><code>option log-health-checks</code>: log health check state changes.</li>
<li><code>pgsql-check</code> checks that PostgreSQL answers, not whether it is the primary.</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 100000
    nbthread 4
    cpu-map auto:1/1-4 0-3
    
    # Security
    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    tcp
    option  tcplog
    option  dontlognull
    option  log-health-checks
    
    timeout connect 5s
    timeout client  3600s
    timeout server  3600s
    timeout check   3s
    
    retries 3
    option  redispatch
    
    default-server inter 3s fall 3 rise 2

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

# PostgreSQL Primary (Read/Write)
frontend pg_write
    bind *:5432
    default_backend pg_primary
    
    # ACL for connection limiting
    acl too_many_conns fe_conn gt 5000
    tcp-request connection reject if too_many_conns

backend pg_primary
    option pgsql-check user haproxy
    server pg-primary 192.168.1.10:5432 check
    server pg-standby1 192.168.1.11:5432 check backup

# PostgreSQL Replicas (Read-Only)
frontend pg_read
    bind *:5433
    default_backend pg_replicas

backend pg_replicas
    balance leastconn
    option pgsql-check user haproxy
    server pg-standby1 192.168.1.11:5432 check
    server pg-standby2 192.168.1.12:5432 check
    server pg-primary  192.168.1.10:5432 check backup  # Fallback

# Redis Cluster
frontend redis
    bind *:6379
    default_backend redis_servers

backend redis_servers
    balance first
    option tcp-check
    tcp-check connect
    tcp-check send &#34;PING\r\n&#34;
    tcp-check expect string +PONG
    tcp-check send &#34;INFO replication\r\n&#34;
    tcp-check expect string role:master
    tcp-check send &#34;QUIT\r\n&#34;
    tcp-check expect string +OK
    server redis1 192.168.1.20:6379 check
    server redis2 192.168.1.21:6379 check
    server redis3 192.168.1.22:6379 check
</code></pre><h2 id="validation-and-testing">Validation and Testing <a class="anchor" data-pagefind-ignore href="#validation-and-testing" aria-label="Link to this section">#</a></h2>
<h3 id="configuration-validation">Configuration Validation <a class="anchor" data-pagefind-ignore href="#configuration-validation" aria-label="Link to this section">#</a></h3>
<p>Check the syntax before every reload.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">haproxy -c -f /etc/haproxy/haproxy.cfg
</span></span></code></pre></div><h3 id="load-testing">Load Testing <a class="anchor" data-pagefind-ignore href="#load-testing" aria-label="Link to this section">#</a></h3>
<p>Open many connections at once, then run a real database benchmark through HAProxy.</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 TCP connection throughput</span>
</span></span><span class="line"><span class="cl"><span class="k">for</span> i in <span class="o">{</span>1..100<span class="o">}</span><span class="p">;</span> <span class="k">do</span>
</span></span><span class="line"><span class="cl">  nc -z -w1 haproxy.example.com <span class="m">5432</span> <span class="p">&amp;</span>
</span></span><span class="line"><span class="cl"><span class="k">done</span>
</span></span><span class="line"><span class="cl"><span class="nb">wait</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># PostgreSQL specific (initialise the pgbench tables once first)</span>
</span></span><span class="line"><span class="cl">pgbench -i -h haproxy.example.com -p <span class="m">5432</span> mydb
</span></span><span class="line"><span class="cl">pgbench -h haproxy.example.com -p <span class="m">5432</span> -c <span class="m">50</span> -j <span class="m">4</span> -T <span class="m">60</span> mydb
</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>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Cause / fix</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Connections dropped after idle time</td>
					<td>Increase <code>timeout server</code> and <code>timeout client</code></td>
			</tr>
			<tr>
					<td>Server marked DOWN</td>
					<td>Check health check configuration and network connectivity</td>
			</tr>
			<tr>
					<td>Connection refused</td>
					<td>Verify backend servers are listening and firewall rules</td>
			</tr>
			<tr>
					<td>Slow connections</td>
					<td>Check <code>balance</code> algorithm and server capacity</td>
			</tr>
			<tr>
					<td>HAProxy does not start on RHEL</td>
					<td>Missing <code>/run/haproxy</code>; see the <code>RuntimeDirectory</code> fix above</td>
			</tr>
	</tbody>
</table>
<h3 id="debug-mode">Debug Mode <a class="anchor" data-pagefind-ignore href="#debug-mode" aria-label="Link to this section">#</a></h3>
<p><code>haproxy -d</code> runs in the foreground and prints every event. The socket commands show process info, per-server stats and the last protocol errors.</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"># Run HAProxy in debug mode</span>
</span></span><span class="line"><span class="cl">haproxy -d -f /etc/haproxy/haproxy.cfg
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check runtime status</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;show info&#34;</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;show stat&#34;</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;show errors&#34;</span> <span class="p">|</span> socat stdio /run/haproxy/admin.sock
</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-haproxy-tcp-lb" rel="noopener">pderuiter/blog-haproxy-tcp-lb</a>. It creates an HAProxy VM on Proxmox and configures the complete production example from this post, PostgreSQL read/write and read-only frontends and the Redis master check included; set your database and Redis servers in <code>group_vars</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: DNS load balancing with HAProxy, to spread DNS queries across multiple resolvers.</p>
<h2 id="summary">Summary <a class="anchor" data-pagefind-ignore href="#summary" aria-label="Link to this section">#</a></h2>
<p>Key takeaways:</p>
<ul>
<li>Use <code>mode tcp</code> for Layer 4 load balancing</li>
<li>Choose the right balancing algorithm for your use case</li>
<li>Implement proper health checks for each protocol</li>
<li>Configure appropriate timeouts for your workload</li>
<li>Use the stats socket for runtime management</li>
<li>Enable logging for troubleshooting and monitoring</li>
</ul>
<p>TCP load balancing is the building block for highly available infrastructure, whether you&rsquo;re running databases, message queues, or custom services.</p>
]]></content:encoded></item><item><title>How to Setup BIND as an Authoritative DNS Server</title><link>https://blog.bsdserver.nl/how-to-setup-bind-as-an-authoritative-dns-server/</link><guid isPermaLink="false">693b6abb79eb54000160a53e</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:07:07 +0000</pubDate><description>An authoritative DNS server is the definitive source of DNS records for the domains it hosts.</description><category>Linux</category><category>DNS</category><category>BIND</category><category>Networking</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/bind-authoritative-dns.png" medium="image"/><content:encoded><![CDATA[<p>An authoritative DNS server is the definitive source of DNS records for the domains it hosts. Unlike recursive resolvers that query other servers, authoritative servers directly answer queries with the records they maintain.</p>
<p>This guide configures BIND 9 as an authoritative-only server: a master that holds the zone files, a slave that copies them by zone transfer, forward and reverse zones, logging and a firewall.</p>
<h2 id="why-authoritative-only">Why Authoritative-Only? <a class="anchor" data-pagefind-ignore href="#why-authoritative-only" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Smaller attack surface</strong>: no recursion means the server cannot be abused as an open resolver.</li>
<li><strong>Predictable load</strong>: it only answers for its own zones, never chases answers elsewhere.</li>
<li><strong>Clear roles</strong>: resolvers for your clients, authoritative servers for the world.</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 you host your own domains (public or internal) and want control over the records.</li>
<li><strong>Skip it</strong> if your registrar or a managed DNS provider already serves your zones and you do not need in-house control.</li>
</ul>
<h3 id="authoritative-vs-recursive">Authoritative vs recursive <a class="anchor" data-pagefind-ignore href="#authoritative-vs-recursive" aria-label="Link to this section">#</a></h3>
<table>
	<thead>
			<tr>
					<th></th>
					<th>Authoritative</th>
					<th>Recursive resolver</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Answers for</td>
					<td>Only the zones it hosts</td>
					<td>Any name, by asking other servers</td>
			</tr>
			<tr>
					<td>Clients</td>
					<td>Anyone on the internet (or your network)</td>
					<td>Your own clients only</td>
			</tr>
			<tr>
					<td>Recursion</td>
					<td>Off</td>
					<td>On</td>
			</tr>
			<tr>
					<td>Covered in</td>
					<td>This post</td>
					<td><a href="https://blog.bsdserver.nl/how-to-setup-bind-as-a-recursive-dns-resolver/">Recursive resolver post</a></td>
			</tr>
	</tbody>
</table>
<h2 id="architecture-overview">Architecture Overview <a class="anchor" data-pagefind-ignore href="#architecture-overview" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Master (<code>type primary</code>)</td>
					<td><code>10.0.0.1</code> (ns1)</td>
					<td>Holds the zone files you edit. Notifies the slave on changes and allows it to transfer.</td>
			</tr>
			<tr>
					<td>Slave (<code>type secondary</code>)</td>
					<td><code>10.0.0.2</code> (ns2)</td>
					<td>Copies the zones from the master and answers queries too.</td>
			</tr>
	</tbody>
</table>
<p>The flow: you edit a zone file on the master and bump the serial → <code>rndc reload</code> → the master sends a NOTIFY → the slave sees a higher serial and transfers the zone → both answer with the new records.</p>
<h2 id="installation">Installation <a class="anchor" data-pagefind-ignore href="#installation" aria-label="Link to this section">#</a></h2>
<p>The package names differ per distribution; both install the server and the <code>dig</code>/<code>named-check*</code> tools.</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 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><h2 id="authoritative-only-configuration">Authoritative-Only Configuration <a class="anchor" data-pagefind-ignore href="#authoritative-only-configuration" aria-label="Link to this section">#</a></h2>
<p>The global <code>options</code> turn recursion off and set safe defaults for every zone. Edit <code>/etc/bind/named.conf.options</code> (Debian) or <code>/etc/named.conf</code> (RHEL).</p>
<ul>
<li><code>recursion no</code> and <code>allow-recursion { none; }</code>: the server only answers for its own zones.</li>
<li><code>allow-query { any; }</code>: anyone may ask, as expected for a public authoritative server.</li>
<li><code>allow-transfer { none; }</code>: no zone transfers by default; each zone opens it for its slave.</li>
<li><code>version &quot;not disclosed&quot;</code>: hides the BIND version from <code>version.bind</code> queries.</li>
<li><code>minimal-responses yes</code>: leaves out optional extra records, so answers are smaller.</li>
<li><code>rate-limit</code>: Response Rate Limiting. Caps identical responses per client, which blunts DNS amplification attacks.</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">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">Listen</span><span class="w"> </span><span class="err">on</span><span class="w"> </span><span class="err">all</span><span class="w"> </span><span class="err">interfaces</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">Disable</span><span class="w"> </span><span class="err">recursion</span><span class="w"> </span><span class="err">-</span><span class="w"> </span><span class="err">this</span><span class="w"> </span><span class="err">is</span><span class="w"> </span><span class="err">authoritative</span><span class="w"> </span><span class="err">only</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">no</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">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">Allow</span><span class="w"> </span><span class="err">queries</span><span class="w"> </span><span class="err">from</span><span class="w"> </span><span class="err">anyone</span><span class="w"> </span><span class="p">(</span><span class="err">public</span><span class="w"> </span><span class="err">authoritative</span><span class="w"> </span><span class="err">server</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-query</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">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="err">by</span><span class="w"> </span><span class="err">default</span><span class="w"> </span><span class="p">(</span><span class="err">override</span><span class="w"> </span><span class="err">per-zone</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></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">Security</span><span class="w"> </span><span class="err">hardening</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 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">Rate</span><span class="w"> </span><span class="err">limiting</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">15</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></code></pre></div><h2 id="zone-configuration">Zone Configuration <a class="anchor" data-pagefind-ignore href="#zone-configuration" aria-label="Link to this section">#</a></h2>
<p>Each zone gets a <code>zone</code> block that says which role this server has for it. Define them in <code>/etc/bind/named.conf.local</code> (Debian) or add them to <code>/etc/named.conf</code> (RHEL).</p>
<table>
	<thead>
			<tr>
					<th>Role</th>
					<th><code>type</code> keyword</th>
					<th>Gets its data from</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Master</td>
					<td><code>primary</code> (older name: <code>master</code>)</td>
					<td>The zone file on disk</td>
			</tr>
			<tr>
					<td>Slave</td>
					<td><code>secondary</code> (older name: <code>slave</code>)</td>
					<td>Zone transfers from the master</td>
			</tr>
	</tbody>
</table>
<h3 id="master-zone">Master Zone <a class="anchor" data-pagefind-ignore href="#master-zone" aria-label="Link to this section">#</a></h3>
<p>On the master, both zones point at a local file and open transfers only for the slave.</p>
<ul>
<li><code>allow-transfer { 10.0.0.2; }</code>: only the slave may copy the zone.</li>
<li><code>also-notify { 10.0.0.2; }</code>: send a NOTIFY to the slave when the zone changes, so it does not wait for its refresh timer.</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">zone</span><span class="w"> </span><span class="err">&#34;</span><span class="nc">example.com</span><span class="err">&#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">primary</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/lib/bind/zones/</span><span class="nc">example.com.zone</span><span class="err">&#34;</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="mi">10.0.0.2</span><span class="c">; };  // Secondary server IP</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">also-notify</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="mi">10.0.0.2</span><span class="c">; };     // Notify secondary on changes</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="err">//</span><span class="w"> </span><span class="err">Reverse</span><span class="w"> </span><span class="err">DNS</span><span class="w"> </span><span class="err">zone</span><span class="w"> </span><span class="err">for</span><span class="w"> </span><span class="mi">192.168.1.0</span><span class="err">/</span><span class="sc">24</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">zone</span><span class="w"> </span><span class="err">&#34;</span><span class="sc">1</span><span class="nc">.168.192.in-addr.arpa</span><span class="err">&#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">primary</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/lib/bind/zones/</span><span class="sc">192</span><span class="nc">.168.1.rev</span><span class="err">&#34;</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="mi">10.0.0.2</span><span class="c">; };</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">also-notify</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="mi">10.0.0.2</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="slave-zone">Slave Zone <a class="anchor" data-pagefind-ignore href="#slave-zone" aria-label="Link to this section">#</a></h3>
<p>On the slave, <code>primaries</code> names the master to transfer from. The <code>file</code> is where BIND stores the transferred copy, so the slave can answer after a restart without a new transfer.</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;</span><span class="nc">example.com</span><span class="err">&#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">secondary</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/lib/bind/zones/</span><span class="nc">example.com.zone</span><span class="err">&#34;</span><span class="c">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="err">primaries</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="mi">10.0.0.1</span><span class="c">; };  // Primary server IP</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="creating-zone-files">Creating Zone Files <a class="anchor" data-pagefind-ignore href="#creating-zone-files" aria-label="Link to this section">#</a></h2>
<p>Zone files live in <code>/var/lib/bind/zones</code>. BIND must own the directory: a slave writes its transferred copies there.</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/lib/bind/zones
</span></span><span class="line"><span class="cl">sudo chown bind:bind /var/lib/bind/zones
</span></span></code></pre></div><h3 id="forward-zone-file">Forward Zone File <a class="anchor" data-pagefind-ignore href="#forward-zone-file" aria-label="Link to this section">#</a></h3>
<p>The forward zone maps names to addresses. Create <code>/var/lib/bind/zones/example.com.zone</code>:</p>
<table>
	<thead>
			<tr>
					<th>Record</th>
					<th>Used for here</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>SOA</code></td>
					<td>Zone metadata and timers (see below)</td>
			</tr>
			<tr>
					<td><code>NS</code> + <code>A</code> for ns1/ns2</td>
					<td>The zone&rsquo;s nameservers and their addresses</td>
			</tr>
			<tr>
					<td><code>MX</code></td>
					<td>Mail servers; lower preference number is tried first</td>
			</tr>
			<tr>
					<td><code>A</code> / <code>AAAA</code></td>
					<td>IPv4 / IPv6 addresses</td>
			</tr>
			<tr>
					<td><code>CNAME</code></td>
					<td>Aliases pointing at another name</td>
			</tr>
			<tr>
					<td><code>TXT</code></td>
					<td>SPF and DMARC policies for mail</td>
			</tr>
	</tbody>
</table>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-dns" data-lang="dns"><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">$ORIGIN</span><span class="w"> </span><span class="py">example.com.</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">2024121201</span><span class="w">  </span><span class="c">; Serial (YYYYMMDDNN)</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 (1 hour)</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 (30 minutes)</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 (1 week)</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="c">; Minimum TTL (1 day)</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="c">; Nameservers</span><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">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="nc">@</span><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></span><span class="line"><span class="cl"><span class="c">; Nameserver A records</span><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">10.0.0.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">10.0.0.2</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="c">; Mail servers</span><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">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="nc">@</span><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">20</span><span class="w">  </span><span class="py">mail2.example.com.</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="c">; A records</span><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">A</span><span class="w">       </span><span class="mi">93.184.216.34</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">93.184.216.34</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">10.0.0.10</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">mail2</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">10.0.0.11</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">ftp</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">10.0.0.20</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="c">; CNAME records</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">webmail</span><span class="w">     </span><span class="k">IN</span><span class="w">  </span><span class="k">CNAME</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="nc">smtp</span><span class="w">        </span><span class="k">IN</span><span class="w">  </span><span class="k">CNAME</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="nc">imap</span><span class="w">        </span><span class="k">IN</span><span class="w">  </span><span class="k">CNAME</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></span><span class="line"><span class="cl"><span class="c">; TXT records for email authentication</span><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">TXT</span><span class="w">     </span><span class="err">&#34;v=spf1</span><span class="w"> </span><span class="err">mx</span><span class="w"> </span><span class="err">a:</span><span class="nc">mail.example.com</span><span class="w"> </span><span class="err">-all&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nc">_dmarc</span><span class="w">      </span><span class="k">IN</span><span class="w">  </span><span class="k">TXT</span><span class="w">     </span><span class="err">&#34;v=DMARC1</span><span class="c">; p=reject; rua=mailto:dmarc@example.com&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c">; AAAA records (IPv6)</span><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">AAAA</span><span class="w">    </span><span class="il">2001:db8::1</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">AAAA</span><span class="w">    </span><span class="il">2001:db8::1</span><span class="w">
</span></span></span></code></pre></div><h3 id="reverse-zone-file">Reverse Zone File <a class="anchor" data-pagefind-ignore href="#reverse-zone-file" aria-label="Link to this section">#</a></h3>
<p>The reverse zone maps addresses back to names with <code>PTR</code> records, used by <code>dig -x</code> and by mail servers checking the sender. The record name is the last octet. Create <code>/var/lib/bind/zones/192.168.1.rev</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-dns" data-lang="dns"><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">$ORIGIN</span><span class="w"> </span><span class="sc">1</span><span class="py">.168.192.in-addr.arpa.</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">2024121201</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="c">; Minimum TTL</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="c">; Nameservers</span><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">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="nc">@</span><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></span><span class="line"><span class="cl"><span class="c">; PTR records</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="sc">1</span><span class="w">       </span><span class="k">IN</span><span class="w">  </span><span class="k">PTR</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="sc">2</span><span class="w">       </span><span class="k">IN</span><span class="w">  </span><span class="k">PTR</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="sc">10</span><span class="w">      </span><span class="k">IN</span><span class="w">  </span><span class="k">PTR</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="sc">11</span><span class="w">      </span><span class="k">IN</span><span class="w">  </span><span class="k">PTR</span><span class="w">     </span><span class="py">mail2.example.com.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="sc">20</span><span class="w">      </span><span class="k">IN</span><span class="w">  </span><span class="k">PTR</span><span class="w">     </span><span class="py">ftp.example.com.</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="sc">100</span><span class="w">     </span><span class="k">IN</span><span class="w">  </span><span class="k">PTR</span><span class="w">     </span><span class="py">server1.example.com.</span><span class="w">
</span></span></span></code></pre></div><h2 id="understanding-the-soa-record">Understanding the SOA Record <a class="anchor" data-pagefind-ignore href="#understanding-the-soa-record" aria-label="Link to this section">#</a></h2>
<p>The SOA timers control how the slave keeps its copy in sync. <code>admin.example.com.</code> is the contact address (<code>admin@example.com</code>).</p>
<table>
	<thead>
			<tr>
					<th>Field</th>
					<th>Description</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Serial</td>
					<td>Version number - increment with each change</td>
			</tr>
			<tr>
					<td>Refresh</td>
					<td>How often secondaries check for updates</td>
			</tr>
			<tr>
					<td>Retry</td>
					<td>How long to wait before retrying failed refresh</td>
			</tr>
			<tr>
					<td>Expire</td>
					<td>When secondary stops serving zone if refresh fails</td>
			</tr>
			<tr>
					<td>Minimum TTL</td>
					<td>Default negative caching TTL</td>
			</tr>
	</tbody>
</table>
<p><strong>Serial number format:</strong> use <code>YYYYMMDDNN</code>, where NN is the revision number for that day. The slave only transfers when the serial goes up.</p>
<h2 id="validate-configuration">Validate Configuration <a class="anchor" data-pagefind-ignore href="#validate-configuration" aria-label="Link to this section">#</a></h2>
<p>Check syntax before every (re)load, so a typo never reaches the running server.</p>
<ul>
<li><code>named-checkconf</code>: the configuration files.</li>
<li><code>named-checkzone &lt;zone&gt; &lt;file&gt;</code>: one zone file, including the SOA and record syntax.</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"># Check named.conf</span>
</span></span><span class="line"><span class="cl">sudo named-checkconf
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check zone files</span>
</span></span><span class="line"><span class="cl">sudo named-checkzone example.com /var/lib/bind/zones/example.com.zone
</span></span><span class="line"><span class="cl">sudo named-checkzone 1.168.192.in-addr.arpa /var/lib/bind/zones/192.168.1.rev
</span></span></code></pre></div><p>Expected output for valid zones:</p>
<pre tabindex="0"><code>zone example.com/IN: loaded serial 2024121201
OK
</code></pre><h2 id="start-and-enable-bind">Start and Enable BIND <a class="anchor" data-pagefind-ignore href="#start-and-enable-bind" 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">sudo systemctl <span class="nb">enable</span> --now named
</span></span><span class="line"><span class="cl">sudo systemctl status named
</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>Query the server directly with <code>dig @localhost</code>. Answers for your zones should carry the <code>aa</code> (authoritative answer) flag. The AXFR from localhost should fail: only the slave is allowed to transfer.</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 the server directly</span>
</span></span><span class="line"><span class="cl">dig @localhost example.com
</span></span><span class="line"><span class="cl">dig @localhost example.com NS
</span></span><span class="line"><span class="cl">dig @localhost example.com MX
</span></span><span class="line"><span class="cl">dig @localhost www.example.com A
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test reverse lookup</span>
</span></span><span class="line"><span class="cl">dig @localhost -x 192.168.1.10
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check SOA record</span>
</span></span><span class="line"><span class="cl">dig @localhost example.com SOA
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test AXFR (zone transfer) - should fail from unauthorized IPs</span>
</span></span><span class="line"><span class="cl">dig @localhost example.com AXFR
</span></span></code></pre></div><h2 id="reload-without-restart">Reload Without Restart <a class="anchor" data-pagefind-ignore href="#reload-without-restart" aria-label="Link to this section">#</a></h2>
<p>After a zone change, <code>rndc reload</code> loads it without restarting the process. Reload a single zone to keep the change contained.</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 all zones</span>
</span></span><span class="line"><span class="cl">sudo 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">sudo rndc reload example.com
</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">sudo rndc status
</span></span></code></pre></div><p><strong>Important:</strong> always increment the serial number when modifying zone files. Without it, the slave keeps serving the old data.</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 log files make transfer problems easy to find. Add this to the configuration:</p>
<ul>
<li><code>channel default_log</code>: general server messages.</li>
<li><code>channel xfer_log</code>: zone transfers in and out, plus NOTIFY messages; the first place to look when the slave is out of sync.</li>
<li><code>versions 3 size 5m</code>: rotate at 5 MB, keep three old files.</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">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">xfer_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">xfer.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">}</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">xfer-in</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">xfer_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">xfer-out</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">xfer_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">notify</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="err">xfer_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 before restarting BIND. If it is missing, <code>named-checkconf</code> still passes but <code>named</code> refuses to start (<code>configuring logging: file not found</code>):</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 class="c1"># RHEL: named:named</span>
</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>DNS uses UDP for normal queries and TCP for large answers and zone transfers, so open both.</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</span>
</span></span><span class="line"><span class="cl">sudo ufw allow 53/tcp
</span></span><span class="line"><span class="cl">sudo ufw allow 53/udp
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># firewalld</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></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>Slave still serves old records</td>
					<td>Serial not incremented on the master; bump it and <code>rndc reload</code></td>
			</tr>
			<tr>
					<td>Zone does not load</td>
					<td>Syntax error; run <code>named-checkzone</code> and check the log</td>
			</tr>
			<tr>
					<td><code>named</code> does not start after adding logging</td>
					<td><code>/var/log/named</code> missing or not owned by the BIND user</td>
			</tr>
			<tr>
					<td>Transfer refused</td>
					<td>Slave IP missing from <code>allow-transfer</code>; check <code>xfer.log</code></td>
			</tr>
			<tr>
					<td>Remote clients time out</td>
					<td>Port 53 closed for UDP or TCP in the firewall</td>
			</tr>
	</tbody>
</table>
<h2 id="best-practices">Best Practices <a class="anchor" data-pagefind-ignore href="#best-practices" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Run at least two authoritative servers</strong> for redundancy.</li>
<li><strong>Use TSIG keys</strong> to authenticate zone transfers between master and slave (see the <a href="https://blog.bsdserver.nl/how-to-configure-bind-rndc-and-tsig-keys-for-remote-dns-management/">rndc and TSIG post</a>).</li>
<li><strong>Implement DNSSEC</strong> for cryptographic validation.</li>
<li><strong>Monitor zone serial numbers</strong> to ensure slaves are synchronized.</li>
<li><strong>Use date-based serial numbers</strong>.</li>
<li><strong>Set appropriate TTLs</strong>: lower for frequently changing records.</li>
<li><strong>Keep logs</strong> for troubleshooting and security auditing.</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-authoritative" rel="noopener">pderuiter/blog-bind-authoritative</a>. It creates two Ubuntu 24.04 VMs on Proxmox and configures the master and slave from this post, with the zones, transfer restrictions, rate limiting and logging; 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 an authoritative-only master and slave. Key points:</p>
<ul>
<li>Authoritative servers only answer for their configured zones; recursion stays off.</li>
<li>The master holds the files, the slave copies them by zone transfer.</li>
<li>Always increment the serial when updating a zone, and validate before reloading.</li>
</ul>
<p>In the next posts, we&rsquo;ll cover securing zone transfers with TSIG keys, implementing DNSSEC, and integrating with dynamic DNS updates.</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>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></channel></rss>