<?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>API | A DevOps Blog</title><link>https://blog.bsdserver.nl/tag/api/</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/api/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 Data Plane API: Dynamic Configuration Management</title><link>https://blog.bsdserver.nl/haproxy-data-plane-api-dynamic-configuration-management/</link><guid isPermaLink="false">693b760079eb54000160a61d</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:55:12 +0000</pubDate><description>Managing HAProxy configuration traditionally requires editing files and reloading the service.</description><category>HAProxy</category><category>API</category><category>Automation</category><category>DevOps</category><category>Infrastructure</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/haproxy-data-plane-api.png" medium="image"/><content:encoded><![CDATA[<p>Managing HAProxy configuration traditionally requires editing files and reloading the service. That works for a person at a terminal, but not for a deployment pipeline that needs to add a server.</p>
<p>The Data Plane API is HAProxy&rsquo;s REST API for its configuration. This post installs it behind a TLS frontend, then uses it to add and remove servers, switch blue-green environments, shift canary traffic, and drive it from Python and GitLab CI.</p>
<h2 id="why-data-plane-api">Why Data Plane API? <a class="anchor" data-pagefind-ignore href="#why-data-plane-api" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Configuration over HTTP</strong> - Backends and servers through REST calls instead of editing <code>haproxy.cfg</code></li>
<li><strong>Transactions</strong> - Group several changes, commit them as one, or throw them away</li>
<li><strong>Version check</strong> - Every change names the configuration version it builds on, so two clients cannot overwrite each other</li>
<li><strong>Runtime changes</strong> - Drain, maintenance and weights on the running process, without a reload</li>
<li><strong>Integration friendly</strong> - Anything that speaks HTTP: shell scripts, Python, CI pipelines</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 tools change HAProxy: deployment pipelines, blue-green switches, service discovery.</li>
<li><strong>Skip it</strong> when the configuration changes rarely and Ansible or another tool already templates <code>haproxy.cfg</code>. That is simpler and easier to review.</li>
</ul>
<p>Pick one owner for <code>haproxy.cfg</code>. Once the API manages it, make changes through the API, not by hand.</p>
<h3 id="configuration-vs-runtime-changes">Configuration vs runtime changes <a class="anchor" data-pagefind-ignore href="#configuration-vs-runtime-changes" aria-label="Link to this section">#</a></h3>
<p>The API has two kinds of endpoints. Knowing which one you call explains most surprises.</p>
<table>
	<thead>
			<tr>
					<th>Endpoints</th>
					<th>Path</th>
					<th>What happens</th>
					<th>Survives a reload</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Configuration</td>
					<td><code>/services/haproxy/configuration/...</code></td>
					<td>Writes <code>haproxy.cfg</code>, then reloads HAProxy</td>
					<td>Yes</td>
			</tr>
			<tr>
					<td>Runtime</td>
					<td><code>/services/haproxy/runtime/...</code></td>
					<td>Changes the running process, no reload</td>
					<td>No</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>HAProxy</td>
					<td>Load balancer</td>
					<td>Serves the application (<code>http_front</code>) and a TLS frontend for the API on port 5556.</td>
			</tr>
			<tr>
					<td>Data Plane API</td>
					<td>Load balancer, port 5555</td>
					<td>Edits <code>haproxy.cfg</code>, reloads HAProxy, and makes runtime changes on the running process.</td>
			</tr>
			<tr>
					<td>Clients</td>
					<td>Admin machine, CI runner</td>
					<td>curl, the scripts below, Python, GitLab CI.</td>
			</tr>
	</tbody>
</table>
<p>The flow: client → HAProxy <code>:5556</code> (TLS, basic auth) → Data Plane API <code>:5555</code> → <code>haproxy.cfg</code> and a reload, or a runtime change.</p>
<h2 id="installing-the-data-plane-api">Installing the Data Plane API <a class="anchor" data-pagefind-ignore href="#installing-the-data-plane-api" aria-label="Link to this section">#</a></h2>
<h3 id="install-haproxy">Install HAProxy <a class="anchor" data-pagefind-ignore href="#install-haproxy" aria-label="Link to this section">#</a></h3>
<p>The Data Plane API 3.x needs a current HAProxy. Install it from the official HAProxy packages rather than the distribution&rsquo;s older <code>haproxy</code> package:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Official HAProxy packages for Ubuntu 24.04: one PPA per branch</span>
</span></span><span class="line"><span class="cl">sudo add-apt-repository -y ppa:vbernat/haproxy-3.3
</span></span><span class="line"><span class="cl">sudo apt update
</span></span><span class="line"><span class="cl">sudo apt install -y <span class="nv">haproxy</span><span class="o">=</span>3.3.<span class="se">\*</span>
</span></span><span class="line"><span class="cl">haproxy -v
</span></span></code></pre></div><p>3.3 is the newest branch the PPA builds for Ubuntu 24.04, but it is a short-lived stable branch, maintained until about Q1 2027. The newest LTS branch, 3.4, is built for Ubuntu 26.04 (<code>ppa:vbernat/haproxy-3.4</code>) and for Debian 13 on <a href="https://haproxy.debian.net/" rel="noopener">haproxy.debian.net</a>, which lists the repository lines per release and branch. For a long-lived Ubuntu 24.04 install, use the 3.2 LTS branch instead (<code>ppa:vbernat/haproxy-3.2</code>, maintained until 2030).</p>
<h3 id="download-and-install">Download and Install <a class="anchor" data-pagefind-ignore href="#download-and-install" aria-label="Link to this section">#</a></h3>
<p>The API is one static binary from the HAProxy Technologies GitHub releases.</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"># Download the latest 3.x release (official HAProxy Technologies build)</span>
</span></span><span class="line"><span class="cl"><span class="nv">DATAPLANEAPI_VERSION</span><span class="o">=</span><span class="s2">&#34;3.4.7&#34;</span>
</span></span><span class="line"><span class="cl">wget https://github.com/haproxytech/dataplaneapi/releases/download/v<span class="si">${</span><span class="nv">DATAPLANEAPI_VERSION</span><span class="si">}</span>/dataplaneapi_<span class="si">${</span><span class="nv">DATAPLANEAPI_VERSION</span><span class="si">}</span>_linux_x86_64.tar.gz
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Extract and install</span>
</span></span><span class="line"><span class="cl">tar xzf dataplaneapi_<span class="si">${</span><span class="nv">DATAPLANEAPI_VERSION</span><span class="si">}</span>_linux_x86_64.tar.gz
</span></span><span class="line"><span class="cl">sudo mv dataplaneapi /usr/local/bin/
</span></span><span class="line"><span class="cl">sudo chmod +x /usr/local/bin/dataplaneapi
</span></span></code></pre></div><p>This post uses the Data Plane API 3.x paths: everything lives under <code>/v3</code>, and servers are addressed through their backend (<code>/services/haproxy/configuration/backends/web_servers/servers</code>). The 2.x style <code>/v2/.../servers?backend=web_servers</code> paths no longer exist.</p>
<h3 id="configuration-file">Configuration File <a class="anchor" data-pagefind-ignore href="#configuration-file" aria-label="Link to this section">#</a></h3>
<p>This file tells the API where to listen, who may log in, and how to reload HAProxy.</p>
<ul>
<li><code>host: 0.0.0.0</code>, <code>port: 5555</code>: the API itself, plain HTTP. Clients use the TLS frontend on 5556 (below).</li>
<li><code>user</code>: the API user. <code>insecure: false</code> means <code>password</code> is a hash, not plain text.</li>
<li><code>transaction_dir</code>: where open transactions wait until they are committed.</li>
<li><code>resources</code>: directories for map files, certificates and SPOE files that the API manages.</li>
<li><code>reload</code>: the commands the API runs. <code>reload_delay: 5</code> is the minimum time in seconds between two reloads.</li>
</ul>
<p>Create <code>/etc/haproxy/dataplaneapi.yaml</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">config_version</span><span class="p">:</span><span class="w"> </span><span class="m">2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">haproxy_dataplane</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">dataplaneapi</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">host</span><span class="p">:</span><span class="w"> </span><span class="m">0.0.0.0</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">port</span><span class="p">:</span><span class="w"> </span><span class="m">5555</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">scheme</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="l">http</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">user</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">admin</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">password</span><span class="p">:</span><span class="w"> </span><span class="l">$6$rounds=500000$...$... </span><span class="w"> </span><span class="c"># Use mkpasswd to generate</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">insecure</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">transaction</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">transaction_dir</span><span class="p">:</span><span class="w"> </span><span class="l">/tmp/haproxy</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">resources</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">maps_dir</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/haproxy/maps</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">ssl_certs_dir</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/haproxy/certs</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">spoe_dir</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/haproxy/spoe</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">spoe_transaction_dir</span><span class="p">:</span><span class="w"> </span><span class="l">/tmp/spoe-haproxy</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">haproxy</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">config_file</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/haproxy/haproxy.cfg</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">haproxy_bin</span><span class="p">:</span><span class="w"> </span><span class="l">/usr/sbin/haproxy</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">reload</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">reload_delay</span><span class="p">:</span><span class="w"> </span><span class="m">5</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">reload_cmd</span><span class="p">:</span><span class="w"> </span><span class="l">systemctl reload haproxy</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">restart_cmd</span><span class="p">:</span><span class="w"> </span><span class="l">systemctl restart haproxy</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">status_cmd</span><span class="p">:</span><span class="w"> </span><span class="l">systemctl status haproxy</span><span class="w">
</span></span></span></code></pre></div><h3 id="generate-password-hash">Generate Password Hash <a class="anchor" data-pagefind-ignore href="#generate-password-hash" aria-label="Link to this section">#</a></h3>
<p>The SHA-512 hash goes into <code>dataplaneapi.yaml</code> and into the HAProxy <code>userlist</code> below.</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 mkpasswd if needed</span>
</span></span><span class="line"><span class="cl">sudo apt install whois
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate SHA-512 password hash</span>
</span></span><span class="line"><span class="cl">mkpasswd -m sha-512 <span class="s1">&#39;your-secure-password&#39;</span>
</span></span></code></pre></div><h2 id="haproxy-configuration-for-api">HAProxy Configuration for API <a class="anchor" data-pagefind-ignore href="#haproxy-configuration-for-api" aria-label="Link to this section">#</a></h2>
<p>HAProxy puts TLS and a second password check in front of the API, and serves the application the examples change.</p>
<ul>
<li><code>stats socket ... level admin</code>: the runtime socket. Runtime changes go through it.</li>
<li><code>frontend dataplane_api</code>: TLS on port 5556 with <code>api.pem</code>, basic auth against <code>api_users</code>, then on to the API on <code>127.0.0.1:5555</code>.</li>
<li><code>userlist api_users</code>: the same user and hash as in <code>dataplaneapi.yaml</code>. The <code>Authorization</code> header is passed on, so the API checks it again.</li>
<li><code>http_front</code> and <code>web_servers</code>: the application. <code>option httpchk GET /health</code> health-checks each server.</li>
</ul>
<p>Add to <code>/etc/haproxy/haproxy.cfg</code>:</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">global
    log /dev/log local0
    chroot /var/lib/haproxy
    stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners
    stats timeout 30s
    user haproxy
    group haproxy
    daemon
    
    # No &#34;master-worker&#34; here: it is deprecated since HAProxy 3.3. The packaged
    # systemd unit already starts HAProxy in master-worker mode (-Ws).

defaults
    log global
    mode http
    option httplog
    option dontlognull
    timeout connect 5000
    timeout client 50000
    timeout server 50000

# Data Plane API Frontend
frontend dataplane_api
    bind *:5556 ssl crt /etc/haproxy/certs/api.pem
    mode http
    http-request auth unless { http_auth(api_users) }
    default_backend dataplane_api_backend

backend dataplane_api_backend
    mode http
    server dataplane 127.0.0.1:5555

userlist api_users
    user admin password $6$rounds=500000$...$...

# Application frontends and backends
frontend http_front
    bind *:80
    bind *:443 ssl crt /etc/haproxy/certs/
    default_backend web_servers

backend web_servers
    balance roundrobin
    option httpchk GET /health
    server web1 192.168.1.10:8080 check
    server web2 192.168.1.11:8080 check
</code></pre><h2 id="starting-the-data-plane-api">Starting the Data Plane API <a class="anchor" data-pagefind-ignore href="#starting-the-data-plane-api" aria-label="Link to this section">#</a></h2>
<h3 id="systemd-service">Systemd Service <a class="anchor" data-pagefind-ignore href="#systemd-service" aria-label="Link to this section">#</a></h3>
<p>The unit starts the API after HAProxy and stops it when HAProxy stops (<code>Requires</code>). It runs as root; the comment in the unit explains why.</p>
<p>Create <code>/etc/systemd/system/dataplaneapi.service</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-ini" data-lang="ini"><span class="line"><span class="cl"><span class="k">[Unit]</span>
</span></span><span class="line"><span class="cl"><span class="na">Description</span><span class="o">=</span><span class="s">HAProxy Data Plane API</span>
</span></span><span class="line"><span class="cl"><span class="na">After</span><span class="o">=</span><span class="s">network.target haproxy.service</span>
</span></span><span class="line"><span class="cl"><span class="na">Requires</span><span class="o">=</span><span class="s">haproxy.service</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">[Service]</span>
</span></span><span class="line"><span class="cl"><span class="na">Type</span><span class="o">=</span><span class="s">simple</span>
</span></span><span class="line"><span class="cl"><span class="na">ExecStart</span><span class="o">=</span><span class="s">/usr/local/bin/dataplaneapi -f /etc/haproxy/dataplaneapi.yaml</span>
</span></span><span class="line"><span class="cl"><span class="na">Restart</span><span class="o">=</span><span class="s">on-failure</span>
</span></span><span class="line"><span class="cl"><span class="na">RestartSec</span><span class="o">=</span><span class="s">5</span>
</span></span><span class="line"><span class="cl"><span class="c1"># Runs as root: it rewrites /etc/haproxy/haproxy.cfg and its own config file,</span>
</span></span><span class="line"><span class="cl"><span class="c1"># and calls systemctl to reload HAProxy. As User=haproxy it exits with</span>
</span></span><span class="line"><span class="cl"><span class="c1"># &#34;Error saving configuration: ... permission denied&#34;.</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">[Install]</span>
</span></span><span class="line"><span class="cl"><span class="na">WantedBy</span><span class="o">=</span><span class="s">multi-user.target</span>
</span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo systemctl daemon-reload
</span></span><span class="line"><span class="cl">sudo systemctl <span class="nb">enable</span> dataplaneapi
</span></span><span class="line"><span class="cl">sudo systemctl start dataplaneapi
</span></span></code></pre></div><h2 id="api-operations">API Operations <a class="anchor" data-pagefind-ignore href="#api-operations" aria-label="Link to this section">#</a></h2>
<h3 id="authentication">Authentication <a class="anchor" data-pagefind-ignore href="#authentication" aria-label="Link to this section">#</a></h3>
<p>All examples use these two variables. <code>/info</code> is a quick test of the connection and the credentials.</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"># Set credentials</span>
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">HAPROXY_API</span><span class="o">=</span><span class="s2">&#34;https://haproxy.example.com:5556/v3&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AUTH</span><span class="o">=</span><span class="s2">&#34;admin:your-secure-password&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test connection</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/info <span class="p">|</span> jq .
</span></span></code></pre></div><h3 id="get-current-configuration">Get Current Configuration <a class="anchor" data-pagefind-ignore href="#get-current-configuration" aria-label="Link to this section">#</a></h3>
<p>Read before you write: the raw configuration, one backend, or its servers.</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"># Get HAProxy configuration</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/services/haproxy/configuration/raw
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Get specific backend</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends/web_servers&#34;</span> <span class="p">|</span> jq .
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># List all servers in a backend</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends/web_servers/servers&#34;</span> <span class="p">|</span> jq .
</span></span></code></pre></div><h3 id="working-with-transactions">Working with Transactions <a class="anchor" data-pagefind-ignore href="#working-with-transactions" aria-label="Link to this section">#</a></h3>
<p>Every configuration change follows the same pattern: version → transaction → changes → commit.</p>
<ul>
<li><strong>Version</strong>: the transaction is tied to the configuration version you read. If another client changed the configuration in between, the API rejects it; start again with a fresh version.</li>
<li><strong>Changes</strong>: calls with <code>?transaction_id=</code> are collected, not applied.</li>
<li><strong>Commit</strong> (<code>PUT</code>): writes all changes to <code>haproxy.cfg</code> at once and reloads HAProxy. <strong>Rollback</strong> (<code>DELETE</code>) throws them away.</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"># Get current configuration version</span>
</span></span><span class="line"><span class="cl"><span class="nv">VERSION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/services/haproxy/configuration/version<span class="k">)</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;Current version: </span><span class="nv">$VERSION</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Start a transaction</span>
</span></span><span class="line"><span class="cl"><span class="nv">TRANSACTION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions?version=</span><span class="nv">$VERSION</span><span class="s2">&#34;</span> <span class="p">|</span> jq -r <span class="s1">&#39;.id&#39;</span><span class="k">)</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;Transaction ID: </span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Make changes within transaction (see examples below)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Commit transaction</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions/</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Or rollback if needed</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X DELETE <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions/</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span>
</span></span></code></pre></div><h3 id="adding-a-server">Adding a Server <a class="anchor" data-pagefind-ignore href="#adding-a-server" aria-label="Link to this section">#</a></h3>
<p><code>check: enabled</code> turns on health checks for the server. <code>weight</code> is its share of the traffic, relative to the other servers in the backend.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Get version and start transaction</span>
</span></span><span class="line"><span class="cl"><span class="nv">VERSION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/services/haproxy/configuration/version<span class="k">)</span>
</span></span><span class="line"><span class="cl"><span class="nv">TRANSACTION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions?version=</span><span class="nv">$VERSION</span><span class="s2">&#34;</span> <span class="p">|</span> jq -r <span class="s1">&#39;.id&#39;</span><span class="k">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Add new server</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends/web_servers/servers?transaction_id=</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d <span class="s1">&#39;{
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;name&#34;: &#34;web3&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;address&#34;: &#34;192.168.1.12&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;port&#34;: 8080,
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;check&#34;: &#34;enabled&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;weight&#34;: 100
</span></span></span><span class="line"><span class="cl"><span class="s1">  }&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Commit changes</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions/</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span>
</span></span></code></pre></div><h3 id="removing-a-server">Removing a Server <a class="anchor" data-pagefind-ignore href="#removing-a-server" aria-label="Link to this section">#</a></h3>
<p>Delete the server by name. Drain it first (see Runtime API Operations) if it still has active connections.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nv">VERSION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/services/haproxy/configuration/version<span class="k">)</span>
</span></span><span class="line"><span class="cl"><span class="nv">TRANSACTION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions?version=</span><span class="nv">$VERSION</span><span class="s2">&#34;</span> <span class="p">|</span> jq -r <span class="s1">&#39;.id&#39;</span><span class="k">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Remove server</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X DELETE <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends/web_servers/servers/web3?transaction_id=</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions/</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span>
</span></span></code></pre></div><h3 id="modifying-server-weight">Modifying Server Weight <a class="anchor" data-pagefind-ignore href="#modifying-server-weight" aria-label="Link to this section">#</a></h3>
<p>A <code>PUT</code> replaces the whole server object, so send every field, not just the weight. The new weight is written to <code>haproxy.cfg</code>; for a temporary change use the runtime weight below.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nv">VERSION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/services/haproxy/configuration/version<span class="k">)</span>
</span></span><span class="line"><span class="cl"><span class="nv">TRANSACTION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions?version=</span><span class="nv">$VERSION</span><span class="s2">&#34;</span> <span class="p">|</span> jq -r <span class="s1">&#39;.id&#39;</span><span class="k">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Update server weight</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends/web_servers/servers/web1?transaction_id=</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d <span class="s1">&#39;{
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;name&#34;: &#34;web1&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;address&#34;: &#34;192.168.1.10&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;port&#34;: 8080,
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;check&#34;: &#34;enabled&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;weight&#34;: 50
</span></span></span><span class="line"><span class="cl"><span class="s1">  }&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions/</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span>
</span></span></code></pre></div><h3 id="creating-a-new-backend">Creating a New Backend <a class="anchor" data-pagefind-ignore href="#creating-a-new-backend" aria-label="Link to this section">#</a></h3>
<p>The backend and its servers go into one transaction, so HAProxy never loads an empty <code>api_servers</code>.</p>
<ul>
<li><code>balance: leastconn</code>: each request goes to the server with the fewest active connections. Good for requests of uneven length.</li>
<li><code>adv_check: httpchk</code> with <code>httpchk_params</code>: health-check every server with <code>GET /health</code>.</li>
</ul>
<p>No frontend sends traffic to <code>api_servers</code> yet; add a <code>use_backend</code> rule for that.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nv">VERSION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/services/haproxy/configuration/version<span class="k">)</span>
</span></span><span class="line"><span class="cl"><span class="nv">TRANSACTION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions?version=</span><span class="nv">$VERSION</span><span class="s2">&#34;</span> <span class="p">|</span> jq -r <span class="s1">&#39;.id&#39;</span><span class="k">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create backend</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends?transaction_id=</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d <span class="s1">&#39;{
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;name&#34;: &#34;api_servers&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;mode&#34;: &#34;http&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;balance&#34;: {&#34;algorithm&#34;: &#34;leastconn&#34;},
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;adv_check&#34;: &#34;httpchk&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;httpchk_params&#34;: {
</span></span></span><span class="line"><span class="cl"><span class="s1">      &#34;method&#34;: &#34;GET&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">      &#34;uri&#34;: &#34;/health&#34;
</span></span></span><span class="line"><span class="cl"><span class="s1">    }
</span></span></span><span class="line"><span class="cl"><span class="s1">  }&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Add servers to new backend</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends/api_servers/servers?transaction_id=</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d <span class="s1">&#39;{&#34;name&#34;: &#34;api1&#34;, &#34;address&#34;: &#34;192.168.1.20&#34;, &#34;port&#34;: 3000, &#34;check&#34;: &#34;enabled&#34;}&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends/api_servers/servers?transaction_id=</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d <span class="s1">&#39;{&#34;name&#34;: &#34;api2&#34;, &#34;address&#34;: &#34;192.168.1.21&#34;, &#34;port&#34;: 3000, &#34;check&#34;: &#34;enabled&#34;}&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions/</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span>
</span></span></code></pre></div><h2 id="runtime-api-operations">Runtime API Operations <a class="anchor" data-pagefind-ignore href="#runtime-api-operations" aria-label="Link to this section">#</a></h2>
<p>Runtime calls change the running HAProxy directly: no transaction, no reload, nothing written to <code>haproxy.cfg</code>. Use them for short-lived changes like taking a server out during a deploy.</p>
<h3 id="server-state-management">Server State Management <a class="anchor" data-pagefind-ignore href="#server-state-management" aria-label="Link to this section">#</a></h3>
<table>
	<thead>
			<tr>
					<th><code>admin_state</code></th>
					<th>Effect</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>drain</code></td>
					<td>No new traffic; existing connections finish</td>
					<td>Before a deploy or a restart</td>
			</tr>
			<tr>
					<td><code>maint</code></td>
					<td>No traffic at all</td>
					<td>A server down for maintenance</td>
			</tr>
			<tr>
					<td><code>ready</code></td>
					<td>Normal operation</td>
					<td>Putting the server back</td>
			</tr>
	</tbody>
</table>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Get server runtime state</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/runtime/backends/web_servers/servers&#34;</span> <span class="p">|</span> jq .
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Disable server (drain mode)</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/runtime/backends/web_servers/servers/web1&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d <span class="s1">&#39;{&#34;admin_state&#34;: &#34;drain&#34;}&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Set server to maintenance</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/runtime/backends/web_servers/servers/web1&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d <span class="s1">&#39;{&#34;admin_state&#34;: &#34;maint&#34;}&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Re-enable server</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/runtime/backends/web_servers/servers/web1&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d <span class="s1">&#39;{&#34;admin_state&#34;: &#34;ready&#34;}&#39;</span>
</span></span></code></pre></div><h3 id="runtime-weight-adjustment">Runtime Weight Adjustment <a class="anchor" data-pagefind-ignore href="#runtime-weight-adjustment" aria-label="Link to this section">#</a></h3>
<p>The runtime weight is not written to <code>haproxy.cfg</code>; it lasts until the next reload.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Adjust weight without reload</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/runtime/backends/web_servers/servers/web1&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d <span class="s1">&#39;{&#34;operational_state&#34;: &#34;up&#34;, &#34;weight&#34;: 150}&#39;</span>
</span></span></code></pre></div><h2 id="automation-scripts">Automation Scripts <a class="anchor" data-pagefind-ignore href="#automation-scripts" aria-label="Link to this section">#</a></h2>
<h3 id="blue-green-deployment-script">Blue-Green Deployment Script <a class="anchor" data-pagefind-ignore href="#blue-green-deployment-script" aria-label="Link to this section">#</a></h3>
<p>Swaps a whole set of servers in one transaction: <code>green</code> adds the green servers and removes the blue ones, <code>blue</code> does the opposite. One commit, so both changes reach HAProxy in the same reload.</p>
<ul>
<li>Servers are listed as <code>name:address:port</code>.</li>
<li><code>--fail-with-body</code> with <code>set -e</code>: a rejected change stops the script before the commit.</li>
<li>Removing ignores errors (<code>|| true</code>), so it also works when the old servers are already gone.</li>
</ul>
<p>Run it as <code>./blue-green-deploy.sh green</code>.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># blue-green-deploy.sh - Switch traffic between blue and green environments</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">set</span> -e
</span></span><span class="line"><span class="cl"><span class="c1"># --fail-with-body makes API errors (4xx/5xx) fail the script instead of</span>
</span></span><span class="line"><span class="cl"><span class="c1"># printing &#34;Deployment complete!&#34; after a rejected change</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">HAPROXY_API</span><span class="o">=</span><span class="s2">&#34;https://haproxy.example.com:5556/v3&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">AUTH</span><span class="o">=</span><span class="s2">&#34;admin:your-secure-password&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">BACKEND</span><span class="o">=</span><span class="s2">&#34;app_servers&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">BLUE_SERVERS</span><span class="o">=(</span><span class="s2">&#34;blue1:192.168.1.10:8080&#34;</span> <span class="s2">&#34;blue2:192.168.1.11:8080&#34;</span><span class="o">)</span>
</span></span><span class="line"><span class="cl"><span class="nv">GREEN_SERVERS</span><span class="o">=(</span><span class="s2">&#34;green1:192.168.1.20:8080&#34;</span> <span class="s2">&#34;green2:192.168.1.21:8080&#34;</span><span class="o">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">get_version<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">  curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/services/haproxy/configuration/version
</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">start_transaction<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">  curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions?version=</span><span class="nv">$1</span><span class="s2">&#34;</span> <span class="p">|</span> jq -r <span class="s1">&#39;.id&#39;</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">add_server<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">  <span class="nb">local</span> <span class="nv">name</span><span class="o">=</span><span class="nv">$1</span>
</span></span><span class="line"><span class="cl">  <span class="nb">local</span> <span class="nv">addr</span><span class="o">=</span><span class="nv">$2</span>
</span></span><span class="line"><span class="cl">  <span class="nb">local</span> <span class="nv">port</span><span class="o">=</span><span class="nv">$3</span>
</span></span><span class="line"><span class="cl">  <span class="nb">local</span> <span class="nv">txn</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">  curl -s --fail-with-body -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends/</span><span class="nv">$BACKEND</span><span class="s2">/servers?transaction_id=</span><span class="nv">$txn</span><span class="s2">&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    -d <span class="s2">&#34;{\&#34;name\&#34;: \&#34;</span><span class="nv">$name</span><span class="s2">\&#34;, \&#34;address\&#34;: \&#34;</span><span class="nv">$addr</span><span class="s2">\&#34;, \&#34;port\&#34;: </span><span class="nv">$port</span><span class="s2">, \&#34;check\&#34;: \&#34;enabled\&#34;}&#34;</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">remove_server<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">  <span class="nb">local</span> <span class="nv">name</span><span class="o">=</span><span class="nv">$1</span>
</span></span><span class="line"><span class="cl">  <span class="nb">local</span> <span class="nv">txn</span><span class="o">=</span><span class="nv">$2</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  curl -s --fail-with-body -u <span class="nv">$AUTH</span> -X DELETE <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends/</span><span class="nv">$BACKEND</span><span class="s2">/servers/</span><span class="si">${</span><span class="nv">name</span><span class="si">}</span><span class="s2">?transaction_id=</span><span class="nv">$txn</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">commit_transaction<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">  curl -s --fail-with-body -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions/</span><span class="nv">$1</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">deploy_environment<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">  <span class="nb">local</span> <span class="nv">target</span><span class="o">=</span><span class="nv">$1</span>
</span></span><span class="line"><span class="cl">  <span class="nb">local</span> servers_to_add
</span></span><span class="line"><span class="cl">  <span class="nb">local</span> servers_to_remove
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  <span class="k">if</span> <span class="o">[</span> <span class="s2">&#34;</span><span class="nv">$target</span><span class="s2">&#34;</span> <span class="o">==</span> <span class="s2">&#34;green&#34;</span> <span class="o">]</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">    <span class="nv">servers_to_add</span><span class="o">=(</span><span class="s2">&#34;</span><span class="si">${</span><span class="nv">GREEN_SERVERS</span><span class="p">[@]</span><span class="si">}</span><span class="s2">&#34;</span><span class="o">)</span>
</span></span><span class="line"><span class="cl">    <span class="nv">servers_to_remove</span><span class="o">=(</span><span class="s2">&#34;</span><span class="si">${</span><span class="nv">BLUE_SERVERS</span><span class="p">[@]</span><span class="si">}</span><span class="s2">&#34;</span><span class="o">)</span>
</span></span><span class="line"><span class="cl">  <span class="k">else</span>
</span></span><span class="line"><span class="cl">    <span class="nv">servers_to_add</span><span class="o">=(</span><span class="s2">&#34;</span><span class="si">${</span><span class="nv">BLUE_SERVERS</span><span class="p">[@]</span><span class="si">}</span><span class="s2">&#34;</span><span class="o">)</span>
</span></span><span class="line"><span class="cl">    <span class="nv">servers_to_remove</span><span class="o">=(</span><span class="s2">&#34;</span><span class="si">${</span><span class="nv">GREEN_SERVERS</span><span class="p">[@]</span><span class="si">}</span><span class="s2">&#34;</span><span class="o">)</span>
</span></span><span class="line"><span class="cl">  <span class="k">fi</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  <span class="nb">echo</span> <span class="s2">&#34;Switching to </span><span class="nv">$target</span><span class="s2"> environment...&#34;</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  <span class="nv">VERSION</span><span class="o">=</span><span class="k">$(</span>get_version<span class="k">)</span>
</span></span><span class="line"><span class="cl">  <span class="nv">TXN</span><span class="o">=</span><span class="k">$(</span>start_transaction <span class="nv">$VERSION</span><span class="k">)</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  <span class="c1"># Add new servers</span>
</span></span><span class="line"><span class="cl">  <span class="k">for</span> server in <span class="s2">&#34;</span><span class="si">${</span><span class="nv">servers_to_add</span><span class="p">[@]</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">;</span> <span class="k">do</span>
</span></span><span class="line"><span class="cl">    <span class="nv">IFS</span><span class="o">=</span><span class="s1">&#39;:&#39;</span> <span class="nb">read</span> -r name addr port <span class="o">&lt;&lt;&lt;</span> <span class="s2">&#34;</span><span class="nv">$server</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="nb">echo</span> <span class="s2">&#34;Adding </span><span class="nv">$name</span><span class="s2"> (</span><span class="nv">$addr</span><span class="s2">:</span><span class="nv">$port</span><span class="s2">)&#34;</span>
</span></span><span class="line"><span class="cl">    add_server <span class="nv">$name</span> <span class="nv">$addr</span> <span class="nv">$port</span> <span class="nv">$TXN</span>
</span></span><span class="line"><span class="cl">  <span class="k">done</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  <span class="c1"># Remove old servers</span>
</span></span><span class="line"><span class="cl">  <span class="k">for</span> server in <span class="s2">&#34;</span><span class="si">${</span><span class="nv">servers_to_remove</span><span class="p">[@]</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">;</span> <span class="k">do</span>
</span></span><span class="line"><span class="cl">    <span class="nv">IFS</span><span class="o">=</span><span class="s1">&#39;:&#39;</span> <span class="nb">read</span> -r name addr port <span class="o">&lt;&lt;&lt;</span> <span class="s2">&#34;</span><span class="nv">$server</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="nb">echo</span> <span class="s2">&#34;Removing </span><span class="nv">$name</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    remove_server <span class="nv">$name</span> <span class="nv">$TXN</span> 2&gt;/dev/null <span class="o">||</span> <span class="nb">true</span>
</span></span><span class="line"><span class="cl">  <span class="k">done</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  commit_transaction <span class="nv">$TXN</span>
</span></span><span class="line"><span class="cl">  <span class="nb">echo</span> <span class="s2">&#34;Deployment complete!&#34;</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">case</span> <span class="s2">&#34;</span><span class="nv">$1</span><span class="s2">&#34;</span> in
</span></span><span class="line"><span class="cl">  blue<span class="o">)</span>  deploy_environment blue <span class="p">;;</span>
</span></span><span class="line"><span class="cl">  green<span class="o">)</span> deploy_environment green <span class="p">;;</span>
</span></span><span class="line"><span class="cl">  *<span class="o">)</span>     <span class="nb">echo</span> <span class="s2">&#34;Usage: </span><span class="nv">$0</span><span class="s2"> {blue|green}&#34;</span> <span class="p">;;</span>
</span></span><span class="line"><span class="cl"><span class="k">esac</span>
</span></span></code></pre></div><h3 id="canary-deployment-script">Canary Deployment Script <a class="anchor" data-pagefind-ignore href="#canary-deployment-script" aria-label="Link to this section">#</a></h3>
<p>Adds one canary server with weight 0, then raises its weight step by step.</p>
<table>
	<thead>
			<tr>
					<th>Command</th>
					<th>What it does</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>add</code></td>
					<td>Adds <code>web-canary</code> to the configuration with weight 0: it receives no traffic yet.</td>
			</tr>
			<tr>
					<td><code>shift &lt;n&gt;</code></td>
					<td>Sets the canary&rsquo;s runtime weight to <code>n</code>. No reload.</td>
			</tr>
			<tr>
					<td><code>remove</code></td>
					<td>Deletes the canary from the configuration.</td>
			</tr>
	</tbody>
</table>
<p>Two things to keep in mind:</p>
<ul>
<li>The weight is relative to the other servers in the backend, and the script does not change those. The printed percentage only matches when the production weights add up to <code>100 - n</code>.</li>
<li>Runtime weights last until the next reload. Any configuration change sets the canary back to weight 0.</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="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># canary-deploy.sh - Gradual traffic shifting to new version</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">set</span> -e
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">HAPROXY_API</span><span class="o">=</span><span class="s2">&#34;https://haproxy.example.com:5556/v3&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">AUTH</span><span class="o">=</span><span class="s2">&#34;admin:your-secure-password&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">BACKEND</span><span class="o">=</span><span class="s2">&#34;web_servers&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">CANARY_SERVER</span><span class="o">=</span><span class="s2">&#34;web-canary&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">CANARY_ADDRESS</span><span class="o">=</span><span class="s2">&#34;192.168.1.50&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">CANARY_PORT</span><span class="o">=</span><span class="s2">&#34;8080&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">shift_traffic<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">  <span class="nb">local</span> <span class="nv">canary_weight</span><span class="o">=</span><span class="nv">$1</span>
</span></span><span class="line"><span class="cl">  <span class="nb">local</span> <span class="nv">production_weight</span><span class="o">=</span><span class="k">$((</span><span class="m">100</span> <span class="o">-</span> canary_weight<span class="k">))</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  <span class="nb">echo</span> <span class="s2">&#34;Shifting traffic: Canary=</span><span class="nv">$canary_weight</span><span class="s2">%, Production=</span><span class="nv">$production_weight</span><span class="s2">%&#34;</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  <span class="c1"># Use runtime API for immediate weight changes</span>
</span></span><span class="line"><span class="cl">  curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/runtime/backends/</span><span class="nv">$BACKEND</span><span class="s2">/servers/</span><span class="si">${</span><span class="nv">CANARY_SERVER</span><span class="si">}</span><span class="s2">&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    -d <span class="s2">&#34;{\&#34;weight\&#34;: </span><span class="nv">$canary_weight</span><span class="s2">}&#34;</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">add_canary<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">  <span class="nv">VERSION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/services/haproxy/configuration/version<span class="k">)</span>
</span></span><span class="line"><span class="cl">  <span class="nv">TXN</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions?version=</span><span class="nv">$VERSION</span><span class="s2">&#34;</span> <span class="p">|</span> jq -r <span class="s1">&#39;.id&#39;</span><span class="k">)</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends/</span><span class="nv">$BACKEND</span><span class="s2">/servers?transaction_id=</span><span class="nv">$TXN</span><span class="s2">&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    -d <span class="s1">&#39;{
</span></span></span><span class="line"><span class="cl"><span class="s1">      &#34;name&#34;: &#34;&#39;</span><span class="nv">$CANARY_SERVER</span><span class="s1">&#39;&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">      &#34;address&#34;: &#34;&#39;</span><span class="nv">$CANARY_ADDRESS</span><span class="s1">&#39;&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">      &#34;port&#34;: &#39;</span><span class="nv">$CANARY_PORT</span><span class="s1">&#39;,
</span></span></span><span class="line"><span class="cl"><span class="s1">      &#34;check&#34;: &#34;enabled&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">      &#34;weight&#34;: 0
</span></span></span><span class="line"><span class="cl"><span class="s1">    }&#39;</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions/</span><span class="nv">$TXN</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">  <span class="nb">echo</span> <span class="s2">&#34;Canary server added with 0% traffic&#34;</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">remove_canary<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">  <span class="nv">VERSION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/services/haproxy/configuration/version<span class="k">)</span>
</span></span><span class="line"><span class="cl">  <span class="nv">TXN</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions?version=</span><span class="nv">$VERSION</span><span class="s2">&#34;</span> <span class="p">|</span> jq -r <span class="s1">&#39;.id&#39;</span><span class="k">)</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  curl -s -u <span class="nv">$AUTH</span> -X DELETE <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends/</span><span class="nv">$BACKEND</span><span class="s2">/servers/</span><span class="si">${</span><span class="nv">CANARY_SERVER</span><span class="si">}</span><span class="s2">?transaction_id=</span><span class="nv">$TXN</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions/</span><span class="nv">$TXN</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">  <span class="nb">echo</span> <span class="s2">&#34;Canary server removed&#34;</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">case</span> <span class="s2">&#34;</span><span class="nv">$1</span><span class="s2">&#34;</span> in
</span></span><span class="line"><span class="cl">  add<span class="o">)</span>    add_canary <span class="p">;;</span>
</span></span><span class="line"><span class="cl">  remove<span class="o">)</span> remove_canary <span class="p">;;</span>
</span></span><span class="line"><span class="cl">  <span class="nb">shift</span><span class="o">)</span>  shift_traffic <span class="nv">$2</span> <span class="p">;;</span>
</span></span><span class="line"><span class="cl">  *<span class="o">)</span>      <span class="nb">echo</span> <span class="s2">&#34;Usage: </span><span class="nv">$0</span><span class="s2"> {add|remove|shift &lt;percentage&gt;}&#34;</span> <span class="p">;;</span>
</span></span><span class="line"><span class="cl"><span class="k">esac</span>
</span></span></code></pre></div><h2 id="python-client-library">Python Client Library <a class="anchor" data-pagefind-ignore href="#python-client-library" aria-label="Link to this section">#</a></h2>
<p>The same calls wrapped in a small class, for tools written in Python.</p>
<ul>
<li><code>add_server</code> and <code>remove_server</code> each run their own transaction, and roll it back when the API rejects the change.</li>
<li><code>set_server_state</code> and <code>set_server_weight</code> are runtime calls: no transaction.</li>
<li><code>session.verify = True</code> checks the API&rsquo;s TLS certificate. Point it at your CA file rather than turning it off.</li>
<li>The <code>time.sleep(6)</code> in the example waits for the reload: a new server only exists in the running HAProxy after <code>reload_delay</code>.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="ch">#!/usr/bin/env python3</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">time</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">requests</span>
</span></span><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">requests.auth</span> <span class="kn">import</span> <span class="n">HTTPBasicAuth</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">json</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">class</span> <span class="nc">HAProxyAPI</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">base_url</span><span class="p">,</span> <span class="n">username</span><span class="p">,</span> <span class="n">password</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="bp">self</span><span class="o">.</span><span class="n">base_url</span> <span class="o">=</span> <span class="n">base_url</span><span class="o">.</span><span class="n">rstrip</span><span class="p">(</span><span class="s1">&#39;/&#39;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="bp">self</span><span class="o">.</span><span class="n">auth</span> <span class="o">=</span> <span class="n">HTTPBasicAuth</span><span class="p">(</span><span class="n">username</span><span class="p">,</span> <span class="n">password</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="bp">self</span><span class="o">.</span><span class="n">session</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">Session</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">        <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">auth</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">auth</span>
</span></span><span class="line"><span class="cl">        <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">verify</span> <span class="o">=</span> <span class="kc">True</span>  <span class="c1"># Set to False for self-signed certs</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">get_version</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;&#34;&#34;Get current configuration version&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="n">r</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="sa">f</span><span class="s2">&#34;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">base_url</span><span class="si">}</span><span class="s2">/services/haproxy/configuration/version&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">r</span><span class="o">.</span><span class="n">text</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">start_transaction</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">version</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;&#34;&#34;Start a new transaction&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="k">if</span> <span class="n">version</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">            <span class="n">version</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_version</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">        <span class="n">r</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="sa">f</span><span class="s2">&#34;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">base_url</span><span class="si">}</span><span class="s2">/services/haproxy/transactions?version=</span><span class="si">{</span><span class="n">version</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">r</span><span class="o">.</span><span class="n">json</span><span class="p">()[</span><span class="s1">&#39;id&#39;</span><span class="p">]</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">commit_transaction</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">txn_id</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;&#34;&#34;Commit a transaction&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="n">r</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="sa">f</span><span class="s2">&#34;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">base_url</span><span class="si">}</span><span class="s2">/services/haproxy/transactions/</span><span class="si">{</span><span class="n">txn_id</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">r</span><span class="o">.</span><span class="n">status_code</span> <span class="o">==</span> <span class="mi">202</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">rollback_transaction</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">txn_id</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;&#34;&#34;Rollback a transaction&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="n">r</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">delete</span><span class="p">(</span><span class="sa">f</span><span class="s2">&#34;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">base_url</span><span class="si">}</span><span class="s2">/services/haproxy/transactions/</span><span class="si">{</span><span class="n">txn_id</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">r</span><span class="o">.</span><span class="n">status_code</span> <span class="o">==</span> <span class="mi">204</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">get_backends</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;&#34;&#34;List all backends&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="n">r</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="sa">f</span><span class="s2">&#34;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">base_url</span><span class="si">}</span><span class="s2">/services/haproxy/configuration/backends&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">r</span><span class="o">.</span><span class="n">json</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">get_servers</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">backend</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;&#34;&#34;List servers in a backend&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="n">r</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">get</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">            <span class="sa">f</span><span class="s2">&#34;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">base_url</span><span class="si">}</span><span class="s2">/services/haproxy/configuration/backends/</span><span class="si">{</span><span class="n">backend</span><span class="si">}</span><span class="s2">/servers&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">r</span><span class="o">.</span><span class="n">json</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">add_server</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">backend</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">address</span><span class="p">,</span> <span class="n">port</span><span class="p">,</span> <span class="n">weight</span><span class="o">=</span><span class="mi">100</span><span class="p">,</span> <span class="n">check</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;&#34;&#34;Add a server to a backend&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="n">txn</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">start_transaction</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="n">data</span> <span class="o">=</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">            <span class="s1">&#39;name&#39;</span><span class="p">:</span> <span class="n">name</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">            <span class="s1">&#39;address&#39;</span><span class="p">:</span> <span class="n">address</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">            <span class="s1">&#39;port&#39;</span><span class="p">:</span> <span class="n">port</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">            <span class="s1">&#39;weight&#39;</span><span class="p">:</span> <span class="n">weight</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">            <span class="s1">&#39;check&#39;</span><span class="p">:</span> <span class="s1">&#39;enabled&#39;</span> <span class="k">if</span> <span class="n">check</span> <span class="k">else</span> <span class="s1">&#39;disabled&#39;</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">r</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">post</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">            <span class="sa">f</span><span class="s2">&#34;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">base_url</span><span class="si">}</span><span class="s2">/services/haproxy/configuration/backends/</span><span class="si">{</span><span class="n">backend</span><span class="si">}</span><span class="s2">/servers&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">            <span class="n">params</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;transaction_id&#39;</span><span class="p">:</span> <span class="n">txn</span><span class="p">},</span>
</span></span><span class="line"><span class="cl">            <span class="n">json</span><span class="o">=</span><span class="n">data</span>
</span></span><span class="line"><span class="cl">        <span class="p">)</span>
</span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="k">if</span> <span class="n">r</span><span class="o">.</span><span class="n">status_code</span> <span class="ow">in</span> <span class="p">[</span><span class="mi">200</span><span class="p">,</span> <span class="mi">201</span><span class="p">,</span> <span class="mi">202</span><span class="p">]:</span>
</span></span><span class="line"><span class="cl">            <span class="bp">self</span><span class="o">.</span><span class="n">commit_transaction</span><span class="p">(</span><span class="n">txn</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">            <span class="k">return</span> <span class="kc">True</span>
</span></span><span class="line"><span class="cl">        <span class="k">else</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">            <span class="bp">self</span><span class="o">.</span><span class="n">rollback_transaction</span><span class="p">(</span><span class="n">txn</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">            <span class="k">return</span> <span class="kc">False</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">remove_server</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">backend</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;&#34;&#34;Remove a server from a backend&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="n">txn</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">start_transaction</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="n">r</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">delete</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">            <span class="sa">f</span><span class="s2">&#34;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">base_url</span><span class="si">}</span><span class="s2">/services/haproxy/configuration/backends/</span><span class="si">{</span><span class="n">backend</span><span class="si">}</span><span class="s2">/servers/</span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">            <span class="n">params</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;transaction_id&#39;</span><span class="p">:</span> <span class="n">txn</span><span class="p">}</span>
</span></span><span class="line"><span class="cl">        <span class="p">)</span>
</span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="k">if</span> <span class="n">r</span><span class="o">.</span><span class="n">status_code</span> <span class="ow">in</span> <span class="p">[</span><span class="mi">200</span><span class="p">,</span> <span class="mi">202</span><span class="p">,</span> <span class="mi">204</span><span class="p">]:</span>
</span></span><span class="line"><span class="cl">            <span class="bp">self</span><span class="o">.</span><span class="n">commit_transaction</span><span class="p">(</span><span class="n">txn</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">            <span class="k">return</span> <span class="kc">True</span>
</span></span><span class="line"><span class="cl">        <span class="k">else</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">            <span class="bp">self</span><span class="o">.</span><span class="n">rollback_transaction</span><span class="p">(</span><span class="n">txn</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">            <span class="k">return</span> <span class="kc">False</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">set_server_state</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">backend</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">state</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;&#34;&#34;Set server runtime state (ready/drain/maint)&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="n">r</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">put</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">            <span class="sa">f</span><span class="s2">&#34;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">base_url</span><span class="si">}</span><span class="s2">/services/haproxy/runtime/backends/</span><span class="si">{</span><span class="n">backend</span><span class="si">}</span><span class="s2">/servers/</span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">            <span class="n">json</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;admin_state&#39;</span><span class="p">:</span> <span class="n">state</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="k">return</span> <span class="n">r</span><span class="o">.</span><span class="n">status_code</span> <span class="o">==</span> <span class="mi">200</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">set_server_weight</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">backend</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">weight</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;&#34;&#34;Set server weight at runtime&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="n">r</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">put</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">            <span class="sa">f</span><span class="s2">&#34;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">base_url</span><span class="si">}</span><span class="s2">/services/haproxy/runtime/backends/</span><span class="si">{</span><span class="n">backend</span><span class="si">}</span><span class="s2">/servers/</span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">            <span class="n">json</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;weight&#39;</span><span class="p">:</span> <span class="n">weight</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="k">return</span> <span class="n">r</span><span class="o">.</span><span class="n">status_code</span> <span class="o">==</span> <span class="mi">200</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Usage example</span>
</span></span><span class="line"><span class="cl"><span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">    <span class="n">api</span> <span class="o">=</span> <span class="n">HAProxyAPI</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">        <span class="s1">&#39;https://haproxy.example.com:5556/v3&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="s1">&#39;admin&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="s1">&#39;your-secure-password&#39;</span>
</span></span><span class="line"><span class="cl">    <span class="p">)</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># List backends</span>
</span></span><span class="line"><span class="cl">    <span class="nb">print</span><span class="p">(</span><span class="s2">&#34;Backends:&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">for</span> <span class="n">backend</span> <span class="ow">in</span> <span class="n">api</span><span class="o">.</span><span class="n">get_backends</span><span class="p">():</span>
</span></span><span class="line"><span class="cl">        <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&#34;  - </span><span class="si">{</span><span class="n">backend</span><span class="p">[</span><span class="s1">&#39;name&#39;</span><span class="p">]</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># List servers</span>
</span></span><span class="line"><span class="cl">    <span class="nb">print</span><span class="p">(</span><span class="s2">&#34;</span><span class="se">\n</span><span class="s2">Servers in web_servers:&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">for</span> <span class="n">server</span> <span class="ow">in</span> <span class="n">api</span><span class="o">.</span><span class="n">get_servers</span><span class="p">(</span><span class="s1">&#39;web_servers&#39;</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&#34;  - </span><span class="si">{</span><span class="n">server</span><span class="p">[</span><span class="s1">&#39;name&#39;</span><span class="p">]</span><span class="si">}</span><span class="s2">: </span><span class="si">{</span><span class="n">server</span><span class="p">[</span><span class="s1">&#39;address&#39;</span><span class="p">]</span><span class="si">}</span><span class="s2">:</span><span class="si">{</span><span class="n">server</span><span class="p">[</span><span class="s1">&#39;port&#39;</span><span class="p">]</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># Add a new server</span>
</span></span><span class="line"><span class="cl">    <span class="nb">print</span><span class="p">(</span><span class="s2">&#34;</span><span class="se">\n</span><span class="s2">Adding new server...&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">api</span><span class="o">.</span><span class="n">add_server</span><span class="p">(</span><span class="s1">&#39;web_servers&#39;</span><span class="p">,</span> <span class="s1">&#39;web4&#39;</span><span class="p">,</span> <span class="s1">&#39;192.168.1.14&#39;</span><span class="p">,</span> <span class="mi">8080</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># The new server exists in the running HAProxy only after the reload</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># (reload_delay); before that the runtime call fails with &#34;not found&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">6</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># Put server in maintenance</span>
</span></span><span class="line"><span class="cl">    <span class="nb">print</span><span class="p">(</span><span class="s2">&#34;Setting web4 to maintenance...&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="nb">print</span><span class="p">(</span><span class="n">api</span><span class="o">.</span><span class="n">set_server_state</span><span class="p">(</span><span class="s1">&#39;web_servers&#39;</span><span class="p">,</span> <span class="s1">&#39;web4&#39;</span><span class="p">,</span> <span class="s1">&#39;maint&#39;</span><span class="p">))</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>
<p>The API can rewrite your whole load balancer. Protect it like root access.</p>
<ul>
<li><strong>Close port 5555.</strong> In the configuration above the API listens on <code>0.0.0.0:5555</code> without TLS. Firewall it, so clients can only use the frontend on 5556.</li>
<li><strong>Keep passwords out of scripts.</strong> The examples set <code>AUTH</code> inline for readability; use a masked CI variable like <code>HAPROXY_AUTH</code> instead.</li>
<li><strong>Restrict who can connect</strong>, and add TLS or mTLS on the API itself (below).</li>
</ul>
<h3 id="tls-configuration">TLS Configuration <a class="anchor" data-pagefind-ignore href="#tls-configuration" aria-label="Link to this section">#</a></h3>
<p>The API can terminate TLS itself. <code>tls_ca</code> makes it require client certificates signed by that CA (mTLS). Keep these files outside <code>/etc/haproxy/certs/</code>, as the comment explains.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="c"># dataplaneapi.yaml with TLS</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">dataplaneapi</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">host</span><span class="p">:</span><span class="w"> </span><span class="m">0.0.0.0</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">port</span><span class="p">:</span><span class="w"> </span><span class="m">5555</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">scheme</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="l">https</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">tls</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># Not in /etc/haproxy/certs/: HAProxy loads every file in that directory</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># for &#34;bind *:443 ssl crt /etc/haproxy/certs/&#34; and fails on a bare key or CA</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">tls_certificate</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/haproxy/api-tls/api.pem</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">tls_key</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/haproxy/api-tls/api.key</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">tls_ca</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/haproxy/api-tls/ca.pem </span><span class="w"> </span><span class="c"># For mTLS</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">tls_port</span><span class="p">:</span><span class="w"> </span><span class="m">5555</span><span class="w">
</span></span></span></code></pre></div><h3 id="network-restrictions">Network Restrictions <a class="anchor" data-pagefind-ignore href="#network-restrictions" aria-label="Link to this section">#</a></h3>
<p>Extra rules on the API frontend:</p>
<ul>
<li><code>acl allowed_networks</code> with <code>http-request deny</code>: only the management networks reach the API.</li>
<li><code>stick-table</code> and <code>track-sc0</code>: count requests per source IP over 10 seconds; above 100 the client gets a 429.</li>
<li>The rules run in order, so blocked clients are refused before the password check.</li>
</ul>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend dataplane_api
    bind *:5556 ssl crt /etc/haproxy/certs/api.pem
    
    # Restrict to management network
    acl allowed_networks src 10.0.0.0/8 192.168.0.0/16
    http-request deny unless allowed_networks
    
    # Rate limiting
    stick-table type ip size 100k expire 30s store http_req_rate(10s)
    http-request track-sc0 src
    http-request deny deny_status 429 if { sc_http_req_rate(0) gt 100 }
    
    http-request auth unless { http_auth(api_users) }
    default_backend dataplane_api_backend
</code></pre><h2 id="integration-with-cicd">Integration with CI/CD <a class="anchor" data-pagefind-ignore href="#integration-with-cicd" aria-label="Link to this section">#</a></h2>
<h3 id="gitlab-ci-example">GitLab CI Example <a class="anchor" data-pagefind-ignore href="#gitlab-ci-example" aria-label="Link to this section">#</a></h3>
<p>The canary flow as a pipeline. <code>HAPROXY_AUTH</code> (<code>user:password</code>) and <code>CANARY_IP</code> come from CI/CD variables.</p>
<table>
	<thead>
			<tr>
					<th>Job</th>
					<th>Runs</th>
					<th>What it does</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>deploy-canary</code></td>
					<td>Automatically on <code>main</code></td>
					<td>Adds <code>canary</code> with weight 10, in a transaction</td>
			</tr>
			<tr>
					<td><code>shift-traffic-50</code></td>
					<td>Manual</td>
					<td>Runtime weight 50</td>
			</tr>
			<tr>
					<td><code>promote-canary</code></td>
					<td>Manual</td>
					<td>Runtime weight 100, drains <code>web1</code> to <code>web3</code></td>
			</tr>
	</tbody>
</table>
<p>The runtime weights go back to 10 at the next reload. Make the promotion permanent with a configuration change.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="c"># .gitlab-ci.yml</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">stages</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="l">deploy</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="l">traffic</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">variables</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">HAPROXY_API</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;https://haproxy.example.com:5556/v3&#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="nt">deploy-canary</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">stage</span><span class="p">:</span><span class="w"> </span><span class="l">deploy</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">script</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="p">|</span><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">      # Add canary server
</span></span></span><span class="line"><span class="cl"><span class="sd">      VERSION=$(curl -s -u $HAPROXY_AUTH $HAPROXY_API/services/haproxy/configuration/version)
</span></span></span><span class="line"><span class="cl"><span class="sd">      TXN=$(curl -s -u $HAPROXY_AUTH -X POST \
</span></span></span><span class="line"><span class="cl"><span class="sd">        &#34;$HAPROXY_API/services/haproxy/transactions?version=$VERSION&#34; | jq -r &#39;.id&#39;)
</span></span></span><span class="line"><span class="cl"><span class="sd">      
</span></span></span><span class="line"><span class="cl"><span class="sd">      curl -s -u $HAPROXY_AUTH -X POST \
</span></span></span><span class="line"><span class="cl"><span class="sd">        &#34;$HAPROXY_API/services/haproxy/configuration/backends/app_servers/servers?transaction_id=$TXN&#34; \
</span></span></span><span class="line"><span class="cl"><span class="sd">        -H &#34;Content-Type: application/json&#34; \
</span></span></span><span class="line"><span class="cl"><span class="sd">        -d &#39;{&#34;name&#34;: &#34;canary&#34;, &#34;address&#34;: &#34;&#39;$CANARY_IP&#39;&#34;, &#34;port&#34;: 8080, &#34;weight&#34;: 10, &#34;check&#34;: &#34;enabled&#34;}&#39;
</span></span></span><span class="line"><span class="cl"><span class="sd">      
</span></span></span><span class="line"><span class="cl"><span class="sd">      curl -s -u $HAPROXY_AUTH -X PUT &#34;$HAPROXY_API/services/haproxy/transactions/$TXN&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">only</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="l">main</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">shift-traffic-50</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">stage</span><span class="p">:</span><span class="w"> </span><span class="l">traffic</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">script</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="p">|</span><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">      curl -s -u $HAPROXY_AUTH -X PUT \
</span></span></span><span class="line"><span class="cl"><span class="sd">        &#34;$HAPROXY_API/services/haproxy/runtime/backends/app_servers/servers/canary&#34; \
</span></span></span><span class="line"><span class="cl"><span class="sd">        -H &#34;Content-Type: application/json&#34; \
</span></span></span><span class="line"><span class="cl"><span class="sd">        -d &#39;{&#34;weight&#34;: 50}&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">when</span><span class="p">:</span><span class="w"> </span><span class="l">manual</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">only</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="l">main</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">promote-canary</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">stage</span><span class="p">:</span><span class="w"> </span><span class="l">traffic</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">script</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="p">|</span><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">      # Shift all traffic to canary
</span></span></span><span class="line"><span class="cl"><span class="sd">      curl -s -u $HAPROXY_AUTH -X PUT \
</span></span></span><span class="line"><span class="cl"><span class="sd">        &#34;$HAPROXY_API/services/haproxy/runtime/backends/app_servers/servers/canary&#34; \
</span></span></span><span class="line"><span class="cl"><span class="sd">        -H &#34;Content-Type: application/json&#34; \
</span></span></span><span class="line"><span class="cl"><span class="sd">        -d &#39;{&#34;weight&#34;: 100}&#39;
</span></span></span><span class="line"><span class="cl"><span class="sd">      
</span></span></span><span class="line"><span class="cl"><span class="sd">      # Set old servers to drain (without the JSON header the API answers 415)
</span></span></span><span class="line"><span class="cl"><span class="sd">      for server in web1 web2 web3; do
</span></span></span><span class="line"><span class="cl"><span class="sd">        curl -s -u $HAPROXY_AUTH -X PUT \
</span></span></span><span class="line"><span class="cl"><span class="sd">          &#34;$HAPROXY_API/services/haproxy/runtime/backends/app_servers/servers/${server}&#34; \
</span></span></span><span class="line"><span class="cl"><span class="sd">          -H &#34;Content-Type: application/json&#34; \
</span></span></span><span class="line"><span class="cl"><span class="sd">          -d &#39;{&#34;admin_state&#34;: &#34;drain&#34;}&#39;
</span></span></span><span class="line"><span class="cl"><span class="sd">      done</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">when</span><span class="p">:</span><span class="w"> </span><span class="l">manual</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">only</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="l">main</span><span class="w">
</span></span></span></code></pre></div><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<h3 id="check-api-status">Check API Status <a class="anchor" data-pagefind-ignore href="#check-api-status" aria-label="Link to this section">#</a></h3>
<p>Is the API up, are transactions left open, and what does HAProxy report?</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 API connectivity</span>
</span></span><span class="line"><span class="cl">curl -v -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/info
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check pending transactions</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/services/haproxy/transactions <span class="p">|</span> jq .
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># View HAProxy stats</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/services/haproxy/stats/native <span class="p">|</span> jq .
</span></span></code></pre></div><h3 id="common-issues">Common Issues <a class="anchor" data-pagefind-ignore href="#common-issues" aria-label="Link to this section">#</a></h3>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Cause / fix</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Transaction or commit rejected over the version</td>
					<td>Another change came first. Fetch a fresh version and start again.</td>
			</tr>
			<tr>
					<td><code>401</code></td>
					<td>Wrong user or password. Through port 5556, check both <code>dataplaneapi.yaml</code> and <code>userlist api_users</code>.</td>
			</tr>
			<tr>
					<td><code>415</code></td>
					<td>The request has no <code>Content-Type: application/json</code> header.</td>
			</tr>
			<tr>
					<td><code>Error saving configuration: ... permission denied</code></td>
					<td>The API does not run as root. See the systemd unit.</td>
			</tr>
			<tr>
					<td>Change rejected as invalid</td>
					<td>Check the current state with the GET endpoints first.</td>
			</tr>
			<tr>
					<td>Reload fails</td>
					<td>Check the syntax with <code>haproxy -c -f /etc/haproxy/haproxy.cfg</code>.</td>
			</tr>
			<tr>
					<td>Runtime call on a new server says &ldquo;not found&rdquo;</td>
					<td>The reload has not happened yet. Wait <code>reload_delay</code>.</td>
			</tr>
			<tr>
					<td>A runtime weight or state is back to its old value</td>
					<td>A reload happened. Runtime changes do not survive it.</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-haproxy-dataplane-api" rel="noopener">pderuiter/blog-haproxy-dataplane-api</a>. It creates an Ubuntu 24.04 VM, installs HAProxy from the official packages and the Data Plane API 3.x behind the TLS frontend from this post; put your <code>mkpasswd</code> hash in the vault and run <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>
<ul>
<li><strong>Service Discovery Integration</strong> - Let the API build backends from Consul: see the <a href="https://blog.bsdserver.nl/haproxy-and-consul-dynamic-service-discovery-for-load-balancing/">Consul post</a></li>
<li><strong>Monitoring</strong> - Track configuration changes and performance metrics</li>
<li><strong>GitOps</strong> - Version control your HAProxy configuration changes</li>
</ul>
<p>With the Data Plane API, HAProxy changes become HTTP calls that scripts and pipelines can make safely.</p>
]]></content:encoded></item><item><title>HAProxy mTLS: Securing API Access with Mutual TLS Authentication</title><link>https://blog.bsdserver.nl/haproxy-mtls-securing-api-access-with-mutual-tls-authentication/</link><guid isPermaLink="false">693b755d79eb54000160a60f</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:52:29 +0000</pubDate><description>Mutual TLS (mTLS) provides strong authentication by requiring both client and server to present certificates.</description><category>HAProxy</category><category>mTLS</category><category>Security</category><category>TLS</category><category>Certificates</category><category>API</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/haproxy-mtls.png" medium="image"/><content:encoded><![CDATA[<p>Mutual TLS (mTLS) provides strong authentication by requiring both client and server to present certificates. API keys and passwords can leak and be replayed; a client certificate proves identity during the TLS handshake, before any request reaches your application.</p>
<p>This guide builds a small internal CA, configures HAProxy to require client certificates, passes the certificate identity to the backends, authorizes by CN, OU or fingerprint, and revokes certificates with a CRL.</p>
<h2 id="what-is-mtls">What is mTLS? <a class="anchor" data-pagefind-ignore href="#what-is-mtls" aria-label="Link to this section">#</a></h2>
<p>In standard TLS, only the server presents a certificate. With mTLS:</p>
<ol>
<li>Server presents its certificate to the client</li>
<li>Client verifies the server certificate</li>
<li>Client presents its certificate to the server</li>
<li>Server verifies the client certificate</li>
</ol>
<p>Both parties are authenticated. HAProxy does the client check, so the backends do not need any TLS code.</p>
<h2 id="why-mtls">Why mTLS? <a class="anchor" data-pagefind-ignore href="#why-mtls" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Service-to-service communication</strong>: Microservices authenticating each other</li>
<li><strong>API security</strong>: Authenticating API clients without passwords</li>
<li><strong>Zero-trust networks</strong>: Verifying identity at every connection</li>
<li><strong>IoT devices</strong>: Authenticating embedded devices</li>
<li><strong>B2B integrations</strong>: Partner API access with certificate-based auth</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> for machine clients you control or issue certificates to: services, devices, partners.</li>
<li><strong>Skip it</strong> for public websites and end users in browsers. Installing certificates on user devices is painful; use OAuth or sessions instead.</li>
</ul>
<h2 id="architecture-overview">Architecture Overview <a class="anchor" data-pagefind-ignore href="#architecture-overview" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Internal CA</td>
					<td>A locked-down host (here: the HAProxy host)</td>
					<td>Signs server and client certificates, publishes the CRL.</td>
			</tr>
			<tr>
					<td>HAProxy</td>
					<td>Load balancer</td>
					<td>Terminates TLS, checks the client certificate against the CA and CRL, applies ACLs, adds identity headers.</td>
			</tr>
			<tr>
					<td>Backends</td>
					<td>App servers</td>
					<td>Receive plain HTTP plus <code>X-Client-*</code> headers.</td>
			</tr>
			<tr>
					<td>Clients</td>
					<td>Services, devices, partners</td>
					<td>Present a certificate signed by the CA.</td>
			</tr>
	</tbody>
</table>
<p>The flow: client connects with its certificate → HAProxy verifies it against <code>ca-file</code> and <code>crl-file</code> → ACLs on CN/OU allow or deny → request goes to a backend with the client identity in headers.</p>
<h2 id="certificate-infrastructure-setup">Certificate Infrastructure Setup <a class="anchor" data-pagefind-ignore href="#certificate-infrastructure-setup" aria-label="Link to this section">#</a></h2>
<h3 id="create-a-certificate-authority-ca">Create a Certificate Authority (CA) <a class="anchor" data-pagefind-ignore href="#create-a-certificate-authority-ca" aria-label="Link to this section">#</a></h3>
<p>Your own CA decides who is a valid client: HAProxy trusts every certificate it signs. Use a private CA, never a public one, or anyone with a public certificate gets in.</p>
<p>What the <code>openssl.cnf</code> sections do:</p>
<table>
	<thead>
			<tr>
					<th>Section</th>
					<th>Use</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>CA_default</code></td>
					<td>Paths, 365-day default validity, 30-day CRL validity. <code>copy_extensions = copy</code> keeps the SAN from the CSR.</td>
			</tr>
			<tr>
					<td><code>policy_strict</code></td>
					<td>Only <code>commonName</code> is required in requests.</td>
			</tr>
			<tr>
					<td><code>v3_ca</code></td>
					<td>Extensions for the CA certificate itself.</td>
			</tr>
			<tr>
					<td><code>usr_cert</code></td>
					<td>Client certificates: <code>extendedKeyUsage = clientAuth</code>.</td>
			</tr>
			<tr>
					<td><code>server_cert</code></td>
					<td>Server certificates: <code>extendedKeyUsage = serverAuth</code>.</td>
			</tr>
	</tbody>
</table>
<p>The CA key is encrypted with a passphrase (<code>-aes256</code>) and the CA certificate is valid for 10 years.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Create CA directory structure</span>
</span></span><span class="line"><span class="cl">mkdir -p /etc/haproxy/ca/<span class="o">{</span>certs,crl,newcerts,private,csr<span class="o">}</span>
</span></span><span class="line"><span class="cl">chmod <span class="m">700</span> /etc/haproxy/ca/private
</span></span><span class="line"><span class="cl">touch /etc/haproxy/ca/index.txt
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="m">1000</span> &gt; /etc/haproxy/ca/serial
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create CA configuration</span>
</span></span><span class="line"><span class="cl">cat &gt; /etc/haproxy/ca/openssl.cnf <span class="s">&lt;&lt; &#39;EOF&#39;
</span></span></span><span class="line"><span class="cl"><span class="s">[ca]
</span></span></span><span class="line"><span class="cl"><span class="s">default_ca = CA_default
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[CA_default]
</span></span></span><span class="line"><span class="cl"><span class="s">dir               = /etc/haproxy/ca
</span></span></span><span class="line"><span class="cl"><span class="s">certs             = $dir/certs
</span></span></span><span class="line"><span class="cl"><span class="s">crl_dir           = $dir/crl
</span></span></span><span class="line"><span class="cl"><span class="s">new_certs_dir     = $dir/newcerts
</span></span></span><span class="line"><span class="cl"><span class="s">database          = $dir/index.txt
</span></span></span><span class="line"><span class="cl"><span class="s">serial            = $dir/serial
</span></span></span><span class="line"><span class="cl"><span class="s">private_key       = $dir/private/ca.key
</span></span></span><span class="line"><span class="cl"><span class="s">certificate       = $dir/certs/ca.crt
</span></span></span><span class="line"><span class="cl"><span class="s">default_md        = sha256
</span></span></span><span class="line"><span class="cl"><span class="s">default_days      = 365
</span></span></span><span class="line"><span class="cl"><span class="s">default_crl_days  = 30
</span></span></span><span class="line"><span class="cl"><span class="s">copy_extensions   = copy
</span></span></span><span class="line"><span class="cl"><span class="s">preserve          = no
</span></span></span><span class="line"><span class="cl"><span class="s">policy            = policy_strict
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[policy_strict]
</span></span></span><span class="line"><span class="cl"><span class="s">countryName             = optional
</span></span></span><span class="line"><span class="cl"><span class="s">stateOrProvinceName     = optional
</span></span></span><span class="line"><span class="cl"><span class="s">localityName            = optional
</span></span></span><span class="line"><span class="cl"><span class="s">organizationName        = optional
</span></span></span><span class="line"><span class="cl"><span class="s">organizationalUnitName  = optional
</span></span></span><span class="line"><span class="cl"><span class="s">commonName              = supplied
</span></span></span><span class="line"><span class="cl"><span class="s">emailAddress            = optional
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[req]
</span></span></span><span class="line"><span class="cl"><span class="s">default_bits        = 4096
</span></span></span><span class="line"><span class="cl"><span class="s">distinguished_name  = req_distinguished_name
</span></span></span><span class="line"><span class="cl"><span class="s">string_mask         = utf8only
</span></span></span><span class="line"><span class="cl"><span class="s">default_md          = sha256
</span></span></span><span class="line"><span class="cl"><span class="s">x509_extensions     = v3_ca
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[req_distinguished_name]
</span></span></span><span class="line"><span class="cl"><span class="s">countryName                     = Country Name (2 letter code)
</span></span></span><span class="line"><span class="cl"><span class="s">stateOrProvinceName             = State or Province Name
</span></span></span><span class="line"><span class="cl"><span class="s">localityName                    = Locality Name
</span></span></span><span class="line"><span class="cl"><span class="s">organizationName                = Organization Name
</span></span></span><span class="line"><span class="cl"><span class="s">organizationalUnitName          = Organizational Unit Name
</span></span></span><span class="line"><span class="cl"><span class="s">commonName                      = Common Name
</span></span></span><span class="line"><span class="cl"><span class="s">emailAddress                    = Email Address
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[v3_ca]
</span></span></span><span class="line"><span class="cl"><span class="s">subjectKeyIdentifier = hash
</span></span></span><span class="line"><span class="cl"><span class="s">authorityKeyIdentifier = keyid:always,issuer
</span></span></span><span class="line"><span class="cl"><span class="s">basicConstraints = critical, CA:true
</span></span></span><span class="line"><span class="cl"><span class="s">keyUsage = critical, digitalSignature, cRLSign, keyCertSign
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[usr_cert]
</span></span></span><span class="line"><span class="cl"><span class="s">basicConstraints = CA:FALSE
</span></span></span><span class="line"><span class="cl"><span class="s">nsCertType = client, email
</span></span></span><span class="line"><span class="cl"><span class="s">nsComment = &#34;Client Certificate&#34;
</span></span></span><span class="line"><span class="cl"><span class="s">subjectKeyIdentifier = hash
</span></span></span><span class="line"><span class="cl"><span class="s">authorityKeyIdentifier = keyid,issuer
</span></span></span><span class="line"><span class="cl"><span class="s">keyUsage = critical, nonRepudiation, digitalSignature, keyEncipherment
</span></span></span><span class="line"><span class="cl"><span class="s">extendedKeyUsage = clientAuth, emailProtection
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[server_cert]
</span></span></span><span class="line"><span class="cl"><span class="s">basicConstraints = CA:FALSE
</span></span></span><span class="line"><span class="cl"><span class="s">nsCertType = server
</span></span></span><span class="line"><span class="cl"><span class="s">nsComment = &#34;Server Certificate&#34;
</span></span></span><span class="line"><span class="cl"><span class="s">subjectKeyIdentifier = hash
</span></span></span><span class="line"><span class="cl"><span class="s">authorityKeyIdentifier = keyid,issuer:always
</span></span></span><span class="line"><span class="cl"><span class="s">keyUsage = critical, digitalSignature, keyEncipherment
</span></span></span><span class="line"><span class="cl"><span class="s">extendedKeyUsage = serverAuth
</span></span></span><span class="line"><span class="cl"><span class="s">EOF</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate CA private key</span>
</span></span><span class="line"><span class="cl">openssl genrsa -aes256 -out /etc/haproxy/ca/private/ca.key <span class="m">4096</span>
</span></span><span class="line"><span class="cl">chmod <span class="m">400</span> /etc/haproxy/ca/private/ca.key
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate CA certificate</span>
</span></span><span class="line"><span class="cl">openssl req -config /etc/haproxy/ca/openssl.cnf <span class="se">\
</span></span></span><span class="line"><span class="cl">  -key /etc/haproxy/ca/private/ca.key <span class="se">\
</span></span></span><span class="line"><span class="cl">  -new -x509 -days <span class="m">3650</span> -sha256 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -extensions v3_ca <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out /etc/haproxy/ca/certs/ca.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  -subj <span class="s2">&#34;/C=US/ST=State/L=City/O=MyOrg/CN=MyOrg CA&#34;</span>
</span></span></code></pre></div><h3 id="generate-server-certificate">Generate Server Certificate <a class="anchor" data-pagefind-ignore href="#generate-server-certificate" aria-label="Link to this section">#</a></h3>
<p>HAProxy presents this certificate to clients on the mTLS port. Clients verify it against the same CA, so they know they talk to the real API. The bind line loads certificate and key from one combined PEM file.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Generate server key</span>
</span></span><span class="line"><span class="cl">mkdir -p /etc/haproxy/certs
</span></span><span class="line"><span class="cl">openssl genrsa -out /etc/haproxy/certs/server.key <span class="m">2048</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate server CSR (clients such as Go and Python require the SAN)</span>
</span></span><span class="line"><span class="cl">openssl req -new <span class="se">\
</span></span></span><span class="line"><span class="cl">  -key /etc/haproxy/certs/server.key <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out /etc/haproxy/ca/csr/server.csr <span class="se">\
</span></span></span><span class="line"><span class="cl">  -subj <span class="s2">&#34;/CN=api.example.com&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -addext <span class="s2">&#34;subjectAltName=DNS:api.example.com&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Sign server certificate with CA</span>
</span></span><span class="line"><span class="cl">openssl ca -config /etc/haproxy/ca/openssl.cnf <span class="se">\
</span></span></span><span class="line"><span class="cl">  -extensions server_cert <span class="se">\
</span></span></span><span class="line"><span class="cl">  -days <span class="m">365</span> -notext -md sha256 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -in /etc/haproxy/ca/csr/server.csr <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out /etc/haproxy/certs/server.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  -batch
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create combined PEM for HAProxy</span>
</span></span><span class="line"><span class="cl">cat /etc/haproxy/certs/server.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">    /etc/haproxy/certs/server.key <span class="se">\
</span></span></span><span class="line"><span class="cl">    &gt; /etc/haproxy/certs/server.pem
</span></span><span class="line"><span class="cl">chmod <span class="m">600</span> /etc/haproxy/certs/server.pem
</span></span></code></pre></div><h3 id="generate-client-certificate">Generate Client Certificate <a class="anchor" data-pagefind-ignore href="#generate-client-certificate" aria-label="Link to this section">#</a></h3>
<p>Every client gets its own certificate, so you can authorize and revoke them one by one. The script takes a name (becomes the CN) and an optional OU (default <code>internal</code>); both are used in the ACLs later.</p>
<table>
	<thead>
			<tr>
					<th>Output</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>.key</code> + <code>.crt</code></td>
					<td>curl, Python, Go, Node.js</td>
			</tr>
			<tr>
					<td><code>.pem</code></td>
					<td>Tools that want certificate and key in one file</td>
			</tr>
			<tr>
					<td><code>.p12</code></td>
					<td>Browsers and Java; password <code>changeme</code>, change it</td>
			</tr>
	</tbody>
</table>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># /usr/local/bin/generate-client-cert.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">CLIENT_NAME</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$1</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">CLIENT_OU</span><span class="o">=</span><span class="s2">&#34;</span><span class="si">${</span><span class="nv">2</span><span class="k">:-</span><span class="nv">internal</span><span class="si">}</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">if</span> <span class="o">[</span> -z <span class="s2">&#34;</span><span class="nv">$CLIENT_NAME</span><span class="s2">&#34;</span> <span class="o">]</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">    <span class="nb">echo</span> <span class="s2">&#34;Usage: </span><span class="nv">$0</span><span class="s2"> &lt;client-name&gt; [organizational-unit]&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="nb">exit</span> <span class="m">1</span>
</span></span><span class="line"><span class="cl"><span class="k">fi</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">CA_DIR</span><span class="o">=</span><span class="s2">&#34;/etc/haproxy/ca&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">OUTPUT_DIR</span><span class="o">=</span><span class="s2">&#34;/etc/haproxy/clients/</span><span class="nv">$CLIENT_NAME</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">mkdir -p <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate client key</span>
</span></span><span class="line"><span class="cl">openssl genrsa -out <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.key&#34;</span> <span class="m">2048</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate client CSR</span>
</span></span><span class="line"><span class="cl">openssl req -new <span class="se">\
</span></span></span><span class="line"><span class="cl">  -key <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.key&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out <span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/csr/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.csr&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -subj <span class="s2">&#34;/OU=</span><span class="nv">$CLIENT_OU</span><span class="s2">/CN=</span><span class="nv">$CLIENT_NAME</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Sign client certificate</span>
</span></span><span class="line"><span class="cl">openssl ca -config <span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/openssl.cnf&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -extensions usr_cert <span class="se">\
</span></span></span><span class="line"><span class="cl">  -days <span class="m">365</span> -notext -md sha256 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -in <span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/csr/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.csr&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.crt&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -batch
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create combined PEM (for applications that need it)</span>
</span></span><span class="line"><span class="cl">cat <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.crt&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.key&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    &gt; <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.pem&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create PKCS12 bundle (for browsers and some clients)</span>
</span></span><span class="line"><span class="cl">openssl pkcs12 -export <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.p12&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -inkey <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.key&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -in <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.crt&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -certfile <span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/certs/ca.crt&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -passout pass:changeme
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;Client certificate generated in </span><span class="nv">$OUTPUT_DIR</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;Files: </span><span class="nv">$CLIENT_NAME</span><span class="s2">.key, </span><span class="nv">$CLIENT_NAME</span><span class="s2">.crt, </span><span class="nv">$CLIENT_NAME</span><span class="s2">.pem, </span><span class="nv">$CLIENT_NAME</span><span class="s2">.p12&#34;</span>
</span></span></code></pre></div><h2 id="basic-mtls-configuration">Basic mTLS Configuration <a class="anchor" data-pagefind-ignore href="#basic-mtls-configuration" aria-label="Link to this section">#</a></h2>
<p>Two bind options switch mTLS on:</p>
<ul>
<li><code>ca-file</code>: the CA that client certificates must be signed by.</li>
<li><code>verify</code>: <code>required</code> rejects the handshake without a valid certificate; <code>optional</code> lets it through and you decide in ACLs.</li>
</ul>
<table>
	<thead>
			<tr>
					<th>Mode</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>verify required</code></td>
					<td>Endpoints only certificate holders may reach</td>
			</tr>
			<tr>
					<td><code>verify optional</code></td>
					<td>One endpoint serving both anonymous and authenticated clients</td>
			</tr>
	</tbody>
</table>
<h3 id="required-mtls">Required mTLS <a class="anchor" data-pagefind-ignore href="#required-mtls" aria-label="Link to this section">#</a></h3>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy"># /etc/haproxy/haproxy.cfg

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

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

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

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

backend authenticated_api
    server api1 192.168.1.10:8080 check

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

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

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

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

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

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

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

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

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

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

backend partner_api
    balance roundrobin
    option httpchk GET /health
    server partner1 192.168.1.40:8080 check
    server partner2 192.168.1.41:8080 check
</code></pre><h2 id="testing-mtls">Testing mTLS <a class="anchor" data-pagefind-ignore href="#testing-mtls" aria-label="Link to this section">#</a></h2>
<p>Test both sides: a request with a certificate must work, one without must fail.</p>
<h3 id="test-with-curl">Test with curl <a class="anchor" data-pagefind-ignore href="#test-with-curl" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Test with client certificate</span>
</span></span><span class="line"><span class="cl">curl -v <span class="se">\
</span></span></span><span class="line"><span class="cl">  --cert /etc/haproxy/clients/api-client/api-client.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  --key /etc/haproxy/clients/api-client/api-client.key <span class="se">\
</span></span></span><span class="line"><span class="cl">  --cacert /etc/haproxy/ca/certs/ca.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  https://api.example.com:8443/api/status
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test with combined PEM</span>
</span></span><span class="line"><span class="cl">curl -v <span class="se">\
</span></span></span><span class="line"><span class="cl">  --cert /etc/haproxy/clients/api-client/api-client.pem <span class="se">\
</span></span></span><span class="line"><span class="cl">  --cacert /etc/haproxy/ca/certs/ca.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  https://api.example.com:8443/api/status
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test without certificate (should fail)</span>
</span></span><span class="line"><span class="cl">curl -v <span class="se">\
</span></span></span><span class="line"><span class="cl">  --cacert /etc/haproxy/ca/certs/ca.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  https://api.example.com:8443/api/status
</span></span></code></pre></div><h3 id="test-with-openssl">Test with openssl <a class="anchor" data-pagefind-ignore href="#test-with-openssl" aria-label="Link to this section">#</a></h3>
<p><code>s_client</code> shows the handshake: the server certificate, whether HAProxy asked for a client certificate, and the verify result.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Connect and show certificate exchange</span>
</span></span><span class="line"><span class="cl">openssl s_client <span class="se">\
</span></span></span><span class="line"><span class="cl">  -connect api.example.com:8443 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -cert /etc/haproxy/clients/api-client/api-client.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  -key /etc/haproxy/clients/api-client/api-client.key <span class="se">\
</span></span></span><span class="line"><span class="cl">  -CAfile /etc/haproxy/ca/certs/ca.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  -verify_return_error
</span></span></code></pre></div><h2 id="client-configuration-examples">Client Configuration Examples <a class="anchor" data-pagefind-ignore href="#client-configuration-examples" aria-label="Link to this section">#</a></h2>
<p>Every client needs the same three files: its certificate, its key, and the CA certificate to verify HAProxy.</p>
<h3 id="python-requests">Python requests <a class="anchor" data-pagefind-ignore href="#python-requests" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">requests</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">response</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">    <span class="s1">&#39;https://api.example.com:8443/api/data&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="n">cert</span><span class="o">=</span><span class="p">(</span><span class="s1">&#39;/path/to/client.crt&#39;</span><span class="p">,</span> <span class="s1">&#39;/path/to/client.key&#39;</span><span class="p">),</span>
</span></span><span class="line"><span class="cl">    <span class="n">verify</span><span class="o">=</span><span class="s1">&#39;/path/to/ca.crt&#39;</span>
</span></span><span class="line"><span class="cl"><span class="p">)</span>
</span></span></code></pre></div><h3 id="nodejs">Node.js <a class="anchor" data-pagefind-ignore href="#nodejs" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-javascript" data-lang="javascript"><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">https</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;https&#39;</span><span class="p">);</span>
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">fs</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;fs&#39;</span><span class="p">);</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">options</span> <span class="o">=</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nx">hostname</span><span class="o">:</span> <span class="s1">&#39;api.example.com&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">port</span><span class="o">:</span> <span class="mi">8443</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">path</span><span class="o">:</span> <span class="s1">&#39;/api/data&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">method</span><span class="o">:</span> <span class="s1">&#39;GET&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">cert</span><span class="o">:</span> <span class="nx">fs</span><span class="p">.</span><span class="nx">readFileSync</span><span class="p">(</span><span class="s1">&#39;/path/to/client.crt&#39;</span><span class="p">),</span>
</span></span><span class="line"><span class="cl">  <span class="nx">key</span><span class="o">:</span> <span class="nx">fs</span><span class="p">.</span><span class="nx">readFileSync</span><span class="p">(</span><span class="s1">&#39;/path/to/client.key&#39;</span><span class="p">),</span>
</span></span><span class="line"><span class="cl">  <span class="nx">ca</span><span class="o">:</span> <span class="nx">fs</span><span class="p">.</span><span class="nx">readFileSync</span><span class="p">(</span><span class="s1">&#39;/path/to/ca.crt&#39;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="p">};</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">req</span> <span class="o">=</span> <span class="nx">https</span><span class="p">.</span><span class="nx">request</span><span class="p">(</span><span class="nx">options</span><span class="p">,</span> <span class="p">(</span><span class="nx">res</span><span class="p">)</span> <span class="p">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="c1">// Handle response
</span></span></span><span class="line"><span class="cl"><span class="p">});</span>
</span></span></code></pre></div><h3 id="go">Go <a class="anchor" data-pagefind-ignore href="#go" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go"><span class="line"><span class="cl"><span class="kn">package</span><span class="w"> </span><span class="nx">main</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="kn">import</span><span class="w"> </span><span class="p">(</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="s">&#34;crypto/tls&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="s">&#34;crypto/x509&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="s">&#34;io/ioutil&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="s">&#34;net/http&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="kd">func</span><span class="w"> </span><span class="nf">main</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nx">cert</span><span class="p">,</span><span class="w"> </span><span class="nx">_</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="nx">tls</span><span class="p">.</span><span class="nf">LoadX509KeyPair</span><span class="p">(</span><span class="s">&#34;client.crt&#34;</span><span class="p">,</span><span class="w"> </span><span class="s">&#34;client.key&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nx">caCert</span><span class="p">,</span><span class="w"> </span><span class="nx">_</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="nx">ioutil</span><span class="p">.</span><span class="nf">ReadFile</span><span class="p">(</span><span class="s">&#34;ca.crt&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nx">caCertPool</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="nx">x509</span><span class="p">.</span><span class="nf">NewCertPool</span><span class="p">()</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nx">caCertPool</span><span class="p">.</span><span class="nf">AppendCertsFromPEM</span><span class="p">(</span><span class="nx">caCert</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nx">client</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="o">&amp;</span><span class="nx">http</span><span class="p">.</span><span class="nx">Client</span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nx">Transport</span><span class="p">:</span><span class="w"> </span><span class="o">&amp;</span><span class="nx">http</span><span class="p">.</span><span class="nx">Transport</span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nx">TLSClientConfig</span><span class="p">:</span><span class="w"> </span><span class="o">&amp;</span><span class="nx">tls</span><span class="p">.</span><span class="nx">Config</span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="nx">Certificates</span><span class="p">:</span><span class="w"> </span><span class="p">[]</span><span class="nx">tls</span><span class="p">.</span><span class="nx">Certificate</span><span class="p">{</span><span class="nx">cert</span><span class="p">},</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="nx">RootCAs</span><span class="p">:</span><span class="w">      </span><span class="nx">caCertPool</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="p">},</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">},</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nx">resp</span><span class="p">,</span><span class="w"> </span><span class="nx">_</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="nx">client</span><span class="p">.</span><span class="nf">Get</span><span class="p">(</span><span class="s">&#34;https://api.example.com:8443/api/data&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c1">// Handle response</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<h3 id="common-errors">Common Errors <a class="anchor" data-pagefind-ignore href="#common-errors" aria-label="Link to this section">#</a></h3>
<table>
	<thead>
			<tr>
					<th>Error</th>
					<th>Cause</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>tlsv1 alert unknown ca</code></td>
					<td>Client certificate not signed by the CA in <code>ca-file</code></td>
			</tr>
			<tr>
					<td><code>SSL certificate verify failed</code></td>
					<td>CA certificate mismatch</td>
			</tr>
			<tr>
					<td><code>tlsv13 alert certificate required</code> (TLS 1.2: handshake failure)</td>
					<td>Client didn&rsquo;t provide certificate when required</td>
			</tr>
			<tr>
					<td><code>ssl/tls alert certificate revoked</code></td>
					<td>Certificate is in CRL</td>
			</tr>
	</tbody>
</table>
<h3 id="debug-commands">Debug Commands <a class="anchor" data-pagefind-ignore href="#debug-commands" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Verify certificate chain</span>
</span></span><span class="line"><span class="cl">openssl verify -CAfile ca.crt client.crt
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check certificate details</span>
</span></span><span class="line"><span class="cl">openssl x509 -in client.crt -text -noout
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check CRL contents</span>
</span></span><span class="line"><span class="cl">openssl crl -in ca.crl -text -noout
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test SSL connection with debug</span>
</span></span><span class="line"><span class="cl">openssl s_client -connect api.example.com:8443 -debug
</span></span></code></pre></div><h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Protect the CA key.</strong> Whoever has it can mint valid client certificates. Keep it encrypted and the CA host locked down.</li>
<li><strong>Short client lifetimes.</strong> 365 days here; shorter limits the damage of a leaked key.</li>
<li><strong>Keep the CRL fresh.</strong> Run the hourly update; an expired CRL locks everyone out.</li>
<li><strong>Do not trust client headers.</strong> Always overwrite <code>X-Client-*</code> in HAProxy, as above, and make backends reachable only through HAProxy.</li>
<li><strong>Change the PKCS12 password</strong> from <code>changeme</code> in the client script.</li>
</ul>
<h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub:
<a href="https://github.com/pderuiter/blog-haproxy-mtls" rel="noopener">pderuiter/blog-haproxy-mtls</a>. It creates an HAProxy VM on Proxmox, builds the internal CA with server and client certificates, and configures the complete production configuration from this post with certificate-based authorization and the hourly CRL update; put the CA passphrase in <code>vault.yml</code>, run <code>terraform apply</code>, then <code>ansible-playbook site.yml</code>.</p>
<h2 id="next-steps">Next Steps <a class="anchor" data-pagefind-ignore href="#next-steps" aria-label="Link to this section">#</a></h2>
<p>Next in the series: the HAProxy Data Plane API for dynamic configuration management.</p>
<h2 id="summary">Summary <a class="anchor" data-pagefind-ignore href="#summary" aria-label="Link to this section">#</a></h2>
<p>Key points for HAProxy mTLS:</p>
<ul>
<li>Use <code>verify required</code> for mandatory client certificates</li>
<li>Use <code>verify optional</code> for mixed authentication</li>
<li>Pass certificate details to backends via headers</li>
<li>Implement authorization based on CN, OU, or fingerprint</li>
<li>Maintain CRL for certificate revocation</li>
<li>Generate unique certificates for each client/service</li>
<li>Test thoroughly with curl and openssl</li>
</ul>
<p>mTLS gives strong mutual authentication without passwords, a good fit for service-to-service communication and API access.</p>
]]></content:encoded></item></channel></rss>