<?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>Ansible | A DevOps Blog</title><link>https://blog.bsdserver.nl/tag/ansible/</link><description>Hands-on DevOps and homelab content: Kubernetes clusters, self-hosted services, CI/CD pipelines and infrastructure as code, by Patrick de Ruiter of We Build Your Cloud.</description><language>en</language><image><url>https://blog.bsdserver.nl/images/app-icon.svg</url><title>A DevOps Blog</title><link>https://blog.bsdserver.nl/</link></image><lastBuildDate>Wed, 18 Nov 2026 09:00:00 +0100</lastBuildDate><atom:link href="https://blog.bsdserver.nl/tag/ansible/rss/" rel="self" type="application/rss+xml"/><ttl>60</ttl><item><title>Automating HAProxy 3.3 and Data Plane API Deployment with Ansible</title><link>https://blog.bsdserver.nl/automating-haproxy-3-1-and-data-plane-api-deployment-with-ansible/</link><guid isPermaLink="false">693b511079eb54000160a47e</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Wed, 18 Nov 2026 09:00:00 +0100</pubDate><description>Introduction HAProxy is one of the most powerful open-source load balancers, widely used for its reliability, security, and performance.</description><category>HAProxy</category><category>Automation</category><category>Ansible</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/ansible-haproxy-data-plane.png" medium="image"/><content:encoded><![CDATA[<p>HAProxy is one of the most powerful open-source load balancers, widely used for its reliability, security, and performance. The Data Plane API adds a REST API to manage its configuration. Installing both by hand means a repository, a pinned package, a binary from GitHub, two config files and a systemd unit, on every load balancer.</p>
<p>This post walks through one Ansible playbook that does all of that, from the official HAProxy repositories, and gives the same result on every run.</p>
<h2 id="why-ansible-for-this">Why Ansible for this? <a class="anchor" data-pagefind-ignore href="#why-ansible-for-this" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Repeatable</strong> - Every load balancer gets the same packages, files and service</li>
<li><strong>Version control</strong> - Change <code>haproxy_version</code> or <code>dataplaneapi_version</code> and rerun to upgrade</li>
<li><strong>Idempotent</strong> - A second run reports no changes, so you can run it at any time</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 more than one load balancer, or for one you want to rebuild quickly.</li>
<li><strong>Skip it</strong> for a single throwaway test box; the manual steps in the <a href="https://blog.bsdserver.nl/haproxy-data-plane-api-dynamic-configuration-management/">Data Plane API post</a> are quicker.</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>Comes from</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>HAProxy</td>
					<td><code>vbernat/haproxy-X.Y</code> PPA (Ubuntu) or haproxy.debian.net (Debian)</td>
					<td>The load balancer.</td>
			</tr>
			<tr>
					<td><code>haproxy.cfg</code></td>
					<td>Template <code>haproxy.cfg.j2</code></td>
					<td>Base config with the stats socket and the API userlist.</td>
			</tr>
			<tr>
					<td>Data Plane API</td>
					<td>GitHub release binary</td>
					<td>REST API that edits <code>haproxy.cfg</code> and reloads HAProxy.</td>
			</tr>
			<tr>
					<td><code>dataplaneapi.yaml</code></td>
					<td>Template <code>dataplaneapi.yaml.j2</code></td>
					<td>API listen address, userlist and reload commands.</td>
			</tr>
			<tr>
					<td><code>dataplaneapi.service</code></td>
					<td>Inline in the playbook</td>
					<td>Starts the API at boot.</td>
			</tr>
	</tbody>
</table>
<p>The flow: add the repository → install HAProxy → write <code>haproxy.cfg</code> → install the API binary → write its config → start the service.</p>
<h2 id="prerequisites">Prerequisites <a class="anchor" data-pagefind-ignore href="#prerequisites" aria-label="Link to this section">#</a></h2>
<p>Before running this playbook, ensure that:</p>
<ul>
<li>You have an Ansible control node with SSH access to the target server.</li>
<li>The target server is running a Debian-based OS (Ubuntu/Debian).</li>
<li>You have sudo privileges on the target machine.</li>
<li>The target can reach the official HAProxy package repositories: the <code>vbernat/haproxy-X.Y</code> PPA on Ubuntu and haproxy.debian.net on Debian. The distribution&rsquo;s own <code>haproxy</code> package is usually a few branches behind.</li>
</ul>
<h3 id="choosing-an-haproxy-branch">Choosing an HAProxy branch <a class="anchor" data-pagefind-ignore href="#choosing-an-haproxy-branch" aria-label="Link to this section">#</a></h3>
<p>HAProxy has two kinds of stable branches:</p>
<table>
	<thead>
			<tr>
					<th>Branch</th>
					<th>Maintained</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>LTS (3.2, 3.4)</td>
					<td>Five years</td>
					<td>Long-lived installs</td>
			</tr>
			<tr>
					<td>Other stable (3.3)</td>
					<td>About a year</td>
					<td>The newest features, if you upgrade often</td>
			</tr>
	</tbody>
</table>
<p>This playbook uses 3.3, the newest branch the PPA builds for Ubuntu 24.04 (3.4 LTS is only built for Ubuntu 26.04 and Debian 13). For a long-lived Ubuntu 24.04 install, set <code>haproxy_version: &quot;3.2&quot;</code> to stay on an LTS branch.</p>
<h2 id="ansible-playbook-for-haproxy-and-data-plane-api-installation">Ansible Playbook for HAProxy and Data Plane API Installation <a class="anchor" data-pagefind-ignore href="#ansible-playbook-for-haproxy-and-data-plane-api-installation" aria-label="Link to this section">#</a></h2>
<p>Below is the complete Ansible playbook to install and configure HAProxy along with the Data Plane API.</p>
<p>The variables at the top:</p>
<table>
	<thead>
			<tr>
					<th>Variable</th>
					<th>Default</th>
					<th>What it sets</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>haproxy_version</code></td>
					<td><code>&quot;3.3&quot;</code></td>
					<td>The repository branch and the pinned package version</td>
			</tr>
			<tr>
					<td><code>dataplaneapi_version</code></td>
					<td><code>&quot;3.4.7&quot;</code></td>
					<td>The API release from GitHub. Changing it upgrades or downgrades.</td>
			</tr>
			<tr>
					<td><code>dataplaneapi_user</code>, <code>dataplaneapi_password</code></td>
					<td><code>admin</code>, <code>adminpwd</code></td>
					<td>The API login. Keep the password in Ansible Vault.</td>
			</tr>
			<tr>
					<td><code>api_bind_address</code>, <code>api_port</code></td>
					<td><code>0.0.0.0</code>, <code>5555</code></td>
					<td>Where the API listens</td>
			</tr>
			<tr>
					<td><code>haproxy_socket</code></td>
					<td><code>/run/haproxy/admin.sock</code></td>
					<td>HAProxy&rsquo;s runtime socket</td>
			</tr>
	</tbody>
</table>
<p>What the tasks do, in order:</p>
<table>
	<thead>
			<tr>
					<th>Tasks</th>
					<th>What they do</th>
					<th>Why this way</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Install <code>python3-debian</code></td>
					<td>Dependency</td>
					<td><code>deb822_repository</code> needs it on the target</td>
			</tr>
			<tr>
					<td>Keyring, <code>stat</code>, <code>get_url</code></td>
					<td>Download the repository signing key</td>
					<td>Only once: the keyserver does not always return identical keys, so a plain download would report a change</td>
			</tr>
			<tr>
					<td><code>deb822_repository</code> (twice)</td>
					<td>Add the PPA on Ubuntu or haproxy.debian.net on Debian</td>
					<td>The suite comes from the OS release, so one playbook fits both</td>
			</tr>
			<tr>
					<td><code>apt haproxy=X.Y.*</code></td>
					<td>Install HAProxy</td>
					<td>Pins the branch. The package cache is only refreshed when the repository was just added.</td>
			</tr>
			<tr>
					<td>Socket directory, <code>haproxy.cfg</code> template</td>
					<td>Base configuration</td>
					<td>A config change restarts HAProxy through the handler</td>
			</tr>
			<tr>
					<td><code>--version</code> check, <code>unarchive</code></td>
					<td>Install the API binary</td>
					<td>Only when the installed version differs from <code>dataplaneapi_version</code></td>
			</tr>
			<tr>
					<td><code>dataplaneapi.yaml</code> template</td>
					<td>API configuration</td>
					<td>root and <code>0600</code>, the same as the API writes it</td>
			</tr>
			<tr>
					<td>systemd unit, <code>systemd</code></td>
					<td>Start the API now and at boot</td>
					<td><code>daemon_reload</code> picks up a new or changed unit</td>
			</tr>
	</tbody>
</table>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nn">---</span><span class="w">
</span></span></span><span class="line"><span class="cl">- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Install and Configure HAProxy with Data Plane API</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">hosts</span><span class="p">:</span><span class="w"> </span><span class="l">your_target_host</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">become</span><span class="p">:</span><span class="w"> </span><span class="kc">yes</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">vars</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_version</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;3.3&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">dataplaneapi_version</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;3.4.7&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">haproxy_user</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;haproxy&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">haproxy_group</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;haproxy&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">dataplaneapi_user</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;admin&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">dataplaneapi_password</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;adminpwd&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">api_bind_address</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;0.0.0.0&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">api_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">haproxy_socket</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;/run/haproxy/admin.sock&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">haproxy_config_file</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;/etc/haproxy/haproxy.cfg&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">dataplaneapi_config_file</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;/etc/haproxy/dataplaneapi.yaml&#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="w">  </span><span class="nt">tasks</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># deb822_repository needs python3-debian on the target</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Install python3-debian</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">apt</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">python3-debian</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">present</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">update_cache</span><span class="p">:</span><span class="w"> </span><span class="kc">yes</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">cache_valid_time</span><span class="p">:</span><span class="w"> </span><span class="m">3600</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># Download the signing keys only once: the keyserver ignores</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># If-Modified-Since and does not always return byte-identical keys, so a</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># plain get_url would report a change on some runs</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">Ensure /etc/apt/keyrings exists</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">file</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/apt/keyrings</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">directory</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">mode</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;0755&#39;</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">name</span><span class="p">:</span><span class="w"> </span><span class="l">Check for the HAProxy repository signing key</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">stat</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;/etc/apt/keyrings/{{ &#39;haproxy-ppa.asc&#39; if ansible_facts[&#39;distribution&#39;] == &#39;Ubuntu&#39; else &#39;haproxy.debian.net.gpg&#39; }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">register</span><span class="p">:</span><span class="w"> </span><span class="l">haproxy_repo_key</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Download the HAProxy PPA signing key (Ubuntu)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">get_url</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">url</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;https://keyserver.ubuntu.com/pks/lookup?op=get&amp;search=0x3D653970FBAB0A890E4E4E9A0F14D8B0CF4EFE96&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">dest</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/apt/keyrings/haproxy-ppa.asc</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">mode</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;0644&#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">ansible_facts[&#39;distribution&#39;] == &#34;Ubuntu&#34; and not haproxy_repo_key.stat.exists</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">name</span><span class="p">:</span><span class="w"> </span><span class="l">Download the haproxy.debian.net signing key (Debian)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">get_url</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">url</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;https://haproxy.debian.net/haproxy-archive-keyring.gpg&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">dest</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/apt/keyrings/haproxy.debian.net.gpg</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">mode</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;0644&#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">ansible_facts[&#39;distribution&#39;] == &#34;Debian&#34; and not haproxy_repo_key.stat.exists</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">name</span><span class="p">:</span><span class="w"> </span><span class="l">Add HAProxy {{ haproxy_version }} Repository (Ubuntu PPA)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">deb822_repository</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">haproxy-{{ haproxy_version }}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">types</span><span class="p">:</span><span class="w"> </span><span class="l">deb</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">uris</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;https://ppa.launchpadcontent.net/vbernat/haproxy-{{ haproxy_version }}/ubuntu&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">suites</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ ansible_facts[&#39;distribution_release&#39;] }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">components</span><span class="p">:</span><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 class="nt">signed_by</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/apt/keyrings/haproxy-ppa.asc</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">register</span><span class="p">:</span><span class="w"> </span><span class="l">haproxy_repo_ubuntu</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">ansible_facts[&#39;distribution&#39;] == &#34;Ubuntu&#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="w">    </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Add HAProxy {{ haproxy_version }} Repository (haproxy.debian.net)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">deb822_repository</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">haproxy-{{ haproxy_version }}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">types</span><span class="p">:</span><span class="w"> </span><span class="l">deb</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">uris</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;http://haproxy.debian.net&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">suites</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ ansible_facts[&#39;distribution_release&#39;] }}-backports-{{ haproxy_version }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">components</span><span class="p">:</span><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 class="nt">signed_by</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/apt/keyrings/haproxy.debian.net.gpg</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">register</span><span class="p">:</span><span class="w"> </span><span class="l">haproxy_repo_debian</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">ansible_facts[&#39;distribution&#39;] == &#34;Debian&#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="w">    </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Install HAProxy {{ haproxy_version }}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">apt</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">haproxy={{ haproxy_version }}.*</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">present</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">update_cache</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ haproxy_repo_ubuntu is changed or haproxy_repo_debian is changed }}&#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="w">    </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Ensure HAProxy socket directory exists</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">file</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ haproxy_socket | dirname }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">directory</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">owner</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ haproxy_user }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">group</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ haproxy_group }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">mode</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;0755&#39;</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">name</span><span class="p">:</span><span class="w"> </span><span class="l">Create HAProxy Configuration</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">template</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">src</span><span class="p">:</span><span class="w"> </span><span class="l">haproxy.cfg.j2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">dest</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ haproxy_config_file }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">owner</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ haproxy_user }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">group</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ haproxy_group }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">mode</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;0644&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">notify</span><span class="p">:</span><span class="w"> </span><span class="l">restart 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="c"># Compare the installed version with the wanted one, so that changing</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># dataplaneapi_version upgrades (or downgrades) an existing install</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">Check installed Data Plane API version</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">command</span><span class="p">:</span><span class="w"> </span><span class="l">/usr/local/bin/dataplaneapi --version</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">register</span><span class="p">:</span><span class="w"> </span><span class="l">dataplaneapi_installed</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">changed_when</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">failed_when</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">name</span><span class="p">:</span><span class="w"> </span><span class="l">Download HAProxy Data Plane API {{ dataplaneapi_version }}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">unarchive</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">src</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;https://github.com/haproxytech/dataplaneapi/releases/download/v{{ dataplaneapi_version }}/dataplaneapi_{{ dataplaneapi_version }}_linux_x86_64.tar.gz&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">dest</span><span class="p">:</span><span class="w"> </span><span class="l">/usr/local/bin</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">remote_src</span><span class="p">:</span><span class="w"> </span><span class="kc">yes</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">include</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- <span class="l">dataplaneapi</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">mode</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;0755&#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">dataplaneapi_installed.stdout is not search(&#39;v&#39; ~ (dataplaneapi_version | regex_escape) ~ &#39; &#39;)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">notify</span><span class="p">:</span><span class="w"> </span><span class="l">restart dataplaneapi</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">name</span><span class="p">:</span><span class="w"> </span><span class="l">Create Data Plane API Configuration</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">template</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">src</span><span class="p">:</span><span class="w"> </span><span class="l">dataplaneapi.yaml.j2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">dest</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ dataplaneapi_config_file }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="c"># root and 0600, like the service: Data Plane API rewrites this</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="c"># file with these permissions every time it starts</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">owner</span><span class="p">:</span><span class="w"> </span><span class="l">root</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">group</span><span class="p">:</span><span class="w"> </span><span class="l">root</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">mode</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;0600&#39;</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">name</span><span class="p">:</span><span class="w"> </span><span class="l">Create systemd service for Data Plane API</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">copy</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">dest</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/systemd/system/dataplaneapi.service</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">content</span><span class="p">:</span><span class="w"> </span><span class="p">|</span><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">          [Unit]
</span></span></span><span class="line"><span class="cl"><span class="sd">          Description=HAProxy Data Plane API
</span></span></span><span class="line"><span class="cl"><span class="sd">          After=network.target haproxy.service
</span></span></span><span class="line"><span class="cl"><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">          [Service]
</span></span></span><span class="line"><span class="cl"><span class="sd">          # -f is the Data Plane API config; --config-file is haproxy.cfg.
</span></span></span><span class="line"><span class="cl"><span class="sd">          # Runs as root: it rewrites haproxy.cfg and calls systemctl reload.
</span></span></span><span class="line"><span class="cl"><span class="sd">          ExecStart=/usr/local/bin/dataplaneapi -f {{ dataplaneapi_config_file }}
</span></span></span><span class="line"><span class="cl"><span class="sd">          Restart=always
</span></span></span><span class="line"><span class="cl"><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">          [Install]
</span></span></span><span class="line"><span class="cl"><span class="sd">          WantedBy=multi-user.target</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">notify</span><span class="p">:</span><span class="w"> </span><span class="l">reload systemd</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">name</span><span class="p">:</span><span class="w"> </span><span class="l">Enable and start Data Plane API service</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">systemd</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">dataplaneapi</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">enabled</span><span class="p">:</span><span class="w"> </span><span class="kc">yes</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">started</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">daemon_reload</span><span class="p">:</span><span class="w"> </span><span class="kc">yes</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">handlers</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">restart haproxy</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">service</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">haproxy</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">restarted</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">name</span><span class="p">:</span><span class="w"> </span><span class="l">reload systemd</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">command</span><span class="p">:</span><span class="w"> </span><span class="l">systemctl daemon-reload</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">name</span><span class="p">:</span><span class="w"> </span><span class="l">restart dataplaneapi</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">service</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">dataplaneapi</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">restarted</span><span class="w">
</span></span></span></code></pre></div><h2 id="haproxy-configuration-template-haproxycfgj2">HAProxy Configuration Template (haproxy.cfg.j2) <a class="anchor" data-pagefind-ignore href="#haproxy-configuration-template-haproxycfgj2" aria-label="Link to this section">#</a></h2>
<p>A minimal starting point. The parts the API needs:</p>
<ul>
<li><code>stats socket ... level admin</code>: the runtime socket for changes without a reload.</li>
<li><code>userlist dataplaneapi</code>: the API login. <code>insecure-password</code> stores it in plain text in <code>haproxy.cfg</code>.</li>
<li><code>frontend http-in</code> / <code>backend servers</code>: a placeholder application to replace with your own.</li>
</ul>
<p>The template task writes this file whenever its content differs, also after changes made through the API. Decide who owns <code>haproxy.cfg</code>: the playbook or the API.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-jinja" data-lang="jinja"><span class="line"><span class="cl"><span class="x">global
</span></span></span><span class="line"><span class="cl"><span class="x">    log /dev/log local0
</span></span></span><span class="line"><span class="cl"><span class="x">    log /dev/log local1 notice
</span></span></span><span class="line"><span class="cl"><span class="x">    stats socket </span><span class="cp">{{</span> <span class="nv">haproxy_socket</span> <span class="cp">}}</span><span class="x"> mode 660 level admin
</span></span></span><span class="line"><span class="cl"><span class="x">    user </span><span class="cp">{{</span> <span class="nv">haproxy_user</span> <span class="cp">}}</span><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">    group </span><span class="cp">{{</span> <span class="nv">haproxy_group</span> <span class="cp">}}</span><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">defaults
</span></span></span><span class="line"><span class="cl"><span class="x">    log     global
</span></span></span><span class="line"><span class="cl"><span class="x">    mode    http
</span></span></span><span class="line"><span class="cl"><span class="x">    option  httplog
</span></span></span><span class="line"><span class="cl"><span class="x">    option  dontlognull
</span></span></span><span class="line"><span class="cl"><span class="x">    timeout connect 5000ms
</span></span></span><span class="line"><span class="cl"><span class="x">    timeout client  50000ms
</span></span></span><span class="line"><span class="cl"><span class="x">    timeout server  50000ms
</span></span></span><span class="line"><span class="cl"><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">userlist dataplaneapi
</span></span></span><span class="line"><span class="cl"><span class="x">    user </span><span class="cp">{{</span> <span class="nv">dataplaneapi_user</span> <span class="cp">}}</span><span class="x"> insecure-password </span><span class="cp">{{</span> <span class="nv">dataplaneapi_password</span> <span class="cp">}}</span><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">frontend http-in
</span></span></span><span class="line"><span class="cl"><span class="x">    bind *:80
</span></span></span><span class="line"><span class="cl"><span class="x">    default_backend servers
</span></span></span><span class="line"><span class="cl"><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">backend servers
</span></span></span><span class="line"><span class="cl"><span class="x">    server server1 127.0.0.1:8000 maxconn 32
</span></span></span></code></pre></div><h2 id="data-plane-api-configuration-template-dataplaneapiyamlj2">Data Plane API Configuration Template (dataplaneapi.yaml.j2) <a class="anchor" data-pagefind-ignore href="#data-plane-api-configuration-template-dataplaneapiyamlj2" aria-label="Link to this section">#</a></h2>
<p>The Data Plane API authenticates against the <code>dataplaneapi</code> userlist in <code>haproxy.cfg</code>. It also rewrites this file in its own normalized form every time it starts, so the template is written in exactly that form; otherwise every playbook run would report it as changed.</p>
<ul>
<li><code>userlist: dataplaneapi</code>: use the userlist from <code>haproxy.cfg</code> instead of users in this file.</li>
<li><code>reload_cmd</code> / <code>restart_cmd</code> with <code>reload_strategy: custom</code>: the API reloads HAProxy through systemd.</li>
<li><code>reload_delay: 5</code>: at most one reload every 5 seconds.</li>
<li><code>log_targets</code> to stdout: the API log ends up in the journal (<code>journalctl -u dataplaneapi</code>).</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-jinja" data-lang="jinja"><span class="line"><span class="cl"><span class="x">config_version: 2
</span></span></span><span class="line"><span class="cl"><span class="x">name: </span><span class="cp">{{</span> <span class="nv">inventory_hostname</span> <span class="cp">}}</span><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">dataplaneapi:
</span></span></span><span class="line"><span class="cl"><span class="x">  host: </span><span class="cp">{{</span> <span class="nv">api_bind_address</span> <span class="cp">}}</span><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">  port: </span><span class="cp">{{</span> <span class="nv">api_port</span> <span class="cp">}}</span><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">  advertised:
</span></span></span><span class="line"><span class="cl"><span class="x">    api_address: &#34;&#34;
</span></span></span><span class="line"><span class="cl"><span class="x">    api_port: 0
</span></span></span><span class="line"><span class="cl"><span class="x">  scheme:
</span></span></span><span class="line"><span class="cl"><span class="x">  - http
</span></span></span><span class="line"><span class="cl"><span class="x">  userlist:
</span></span></span><span class="line"><span class="cl"><span class="x">    userlist: dataplaneapi
</span></span></span><span class="line"><span class="cl"><span class="x">    userlist_file: &#34;&#34;
</span></span></span><span class="line"><span class="cl"><span class="x">  transaction:
</span></span></span><span class="line"><span class="cl"><span class="x">    transaction_dir: /tmp/haproxy
</span></span></span><span class="line"><span class="cl"><span class="x">haproxy:
</span></span></span><span class="line"><span class="cl"><span class="x">  config_file: </span><span class="cp">{{</span> <span class="nv">haproxy_config_file</span> <span class="cp">}}</span><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">  haproxy_bin: /usr/sbin/haproxy
</span></span></span><span class="line"><span class="cl"><span class="x">  reload:
</span></span></span><span class="line"><span class="cl"><span class="x">    reload_delay: 5
</span></span></span><span class="line"><span class="cl"><span class="x">    reload_cmd: systemctl reload haproxy
</span></span></span><span class="line"><span class="cl"><span class="x">    restart_cmd: systemctl restart haproxy
</span></span></span><span class="line"><span class="cl"><span class="x">    reload_strategy: custom
</span></span></span><span class="line"><span class="cl"><span class="x">log_targets:
</span></span></span><span class="line"><span class="cl"><span class="x">- log_to: stdout
</span></span></span><span class="line"><span class="cl"><span class="x">  log_level: info
</span></span></span></code></pre></div><h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Store the password in Ansible Vault</strong>, not in the playbook. <code>adminpwd</code> is an example.</li>
<li><strong>Use a hashed password.</strong> <code>insecure-password</code> keeps it readable in <code>haproxy.cfg</code>; HAProxy userlists also accept a hash with <code>password</code>.</li>
<li><strong>Limit <code>api_bind_address</code>.</strong> <code>0.0.0.0</code> with plain HTTP exposes the API and its password to the network. Bind it to <code>127.0.0.1</code> or a management address, or put TLS in front as in the <a href="https://blog.bsdserver.nl/haproxy-data-plane-api-dynamic-configuration-management/">Data Plane API post</a>.</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 playbook from this post, split into roles, plus Terraform code for the machine, is on GitHub:
<a href="https://github.com/pderuiter/blog-haproxy-ansible" rel="noopener">pderuiter/blog-haproxy-ansible</a>. It creates an Ubuntu 24.04 VM and installs HAProxy and the Data Plane API exactly as above; set the API password in the vault and run <code>ansible-playbook site.yml</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>One playbook installs HAProxy and the Data Plane API the same way on every machine, and a version bump is a variable change.</p>
<p>Next: use the API to manage backends (<a href="https://blog.bsdserver.nl/haproxy-data-plane-api-dynamic-configuration-management/">Data Plane API post</a>) or to fill them from Consul (<a href="https://blog.bsdserver.nl/haproxy-and-consul-dynamic-service-discovery-for-load-balancing/">Consul post</a>).</p>
]]></content:encoded></item><item><title>Why We Chose CFEngine Instead of Ansible for Configuration Management</title><link>https://blog.bsdserver.nl/why-we-chose-cfengine-instead-of-ansible-for-configuration-management/</link><guid isPermaLink="false">6a61dd6418bfa60001dd6cfd</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 24 Jul 2026 19:13:06 +0000</pubDate><description>Ask ten engineers which configuration management tool to use and nine will say Ansible. We went the other way.</description><category>Automation</category><category>Ansible</category><category>DevOps</category><category>Infrastructure</category><media:content url="https://blog.bsdserver.nl/content/images/2026/07/cfengine-vs-ansible.png" medium="image"/><content:encoded><![CDATA[<p>Ask ten engineers which configuration management tool to use and nine will say Ansible. We went the other way. Our fleet, both on-premise and cloud, for clients who expect things to just keep running, is managed by CFEngine. Here are the ten reasons why, and where Ansible still earns its place in our stack.</p>
<h2 id="1-continuous-convergence-not-point-in-time-runs">1. Continuous convergence, not point-in-time runs <a class="anchor" data-pagefind-ignore href="#1-continuous-convergence-not-point-in-time-runs" aria-label="Link to this section">#</a></h2>
<p>Ansible configures a host at the moment you run a playbook. Between runs, nothing watches the machine. CFEngine&rsquo;s agent runs every five minutes, every day, forever. Someone hand-edits a config, a package update overwrites a file, a service dies in the middle of the night, the agent quietly puts it back.</p>
<h2 id="2-self-healing-by-design">2. Self-healing by design <a class="anchor" data-pagefind-ignore href="#2-self-healing-by-design" aria-label="Link to this section">#</a></h2>
<p>Because the agent converges continuously, repair isn&rsquo;t a special event, it&rsquo;s the default behaviour. We don&rsquo;t get paged to re-run a playbook; drift is corrected before monitoring even fires. For a managed hosting company, that&rsquo;s not a nice-to-have.</p>
<h2 id="3-pull-beats-push-at-scale">3. Pull beats push at scale <a class="anchor" data-pagefind-ignore href="#3-pull-beats-push-at-scale" aria-label="Link to this section">#</a></h2>
<p>Ansible pushes over SSH from a control node: one machine fanning out to hundreds. Slow runs, timeouts, and a controller that becomes a bottleneck and a single point of failure. CFEngine hosts pull their policy from a hub and execute locally. A thousand hosts converging is no harder than ten, the work is distributed to the machines themselves.</p>
<h2 id="4-a-tiny-dependency-free-footprint">4. A tiny, dependency-free footprint <a class="anchor" data-pagefind-ignore href="#4-a-tiny-dependency-free-footprint" aria-label="Link to this section">#</a></h2>
<p>The CFEngine agent is written in C. It uses a few tens of megabytes of memory and needs no interpreter on the managed host. Ansible needs Python on every target, a real constraint on minimal installs, appliances, and BSD systems. We run infrastructure on machines where a Python runtime is either unwelcome or unavailable. The C agent runs everywhere, including the smallest VPS we manage.</p>
<h2 id="5-speed">5. Speed <a class="anchor" data-pagefind-ignore href="#5-speed" aria-label="Link to this section">#</a></h2>
<p>An agent run over our full policy set completes in seconds. Comparable Ansible playbooks take minutes per host, dominated by SSH round-trips and module transfer. Multiply that across a fleet and across every change, and the difference stops being academic.</p>
<h2 id="6-hosts-stay-autonomous">6. Hosts stay autonomous <a class="anchor" data-pagefind-ignore href="#6-hosts-stay-autonomous" aria-label="Link to this section">#</a></h2>
<p>Every CFEngine host caches its policy. If the policy server is unreachable, due to network partition, hub maintenance, or datacenter issue, hosts keep enforcing the last known-good policy on their own. An Ansible-managed fleet with an unreachable control node is simply unmanaged until it comes back.</p>
<h2 id="7-a-stronger-security-posture">7. A stronger security posture <a class="anchor" data-pagefind-ignore href="#7-a-stronger-security-posture" aria-label="Link to this section">#</a></h2>
<p>An Ansible control node holds SSH keys with root access to your entire estate, a high-value target. CFEngine inverts this: no inbound management connections needed, mutual authentication between agent and hub, and policy distributed over a trusted channel. Compromising the hub doesn&rsquo;t hand an attacker an interactive root shell on every host.</p>
<h2 id="8-promise-theory-makes-intent-explicit">8. Promise theory makes intent explicit <a class="anchor" data-pagefind-ignore href="#8-promise-theory-makes-intent-explicit" aria-label="Link to this section">#</a></h2>
<p>Ansible playbooks are ordered task lists, closer to structured scripting than desired state. CFEngine policies are promises: declarations of the state a host should converge to, with the agent deciding what needs doing. The learning curve is steeper, but once it clicks, policies are more predictable and genuinely idempotent, not idempotent-if-every-module-author-did-their-job.</p>
<h2 id="9-drift-detection-and-reporting-built-in">9. Drift detection and reporting built in <a class="anchor" data-pagefind-ignore href="#9-drift-detection-and-reporting-built-in" aria-label="Link to this section">#</a></h2>
<p>Because agents evaluate state constantly, CFEngine knows what changed, on which host, and when. Fleet-wide inventory and compliance reporting come with the model. With Ansible you only learn about drift when you happen to run a playbook in check mode. For compliance conversations with clients, &ldquo;here&rsquo;s a continuous report&rdquo; beats &ldquo;we ran a scan last Tuesday.&rdquo;</p>
<p>Homelabbers can have this too: CFEngine Enterprise is free for up to 25 hosts.</p>
<h2 id="10-boring-in-the-best-way">10. Boring in the best way <a class="anchor" data-pagefind-ignore href="#10-boring-in-the-best-way" aria-label="Link to this section">#</a></h2>
<p>CFEngine has been maintaining production systems since 1993. The language and the model are stable; policies we wrote years ago still run unmodified. That predictability matters when you&rsquo;re promising clients long-term managed infrastructure, not chasing this year&rsquo;s tooling refresh.</p>
<h2 id="where-ansible-still-fits">Where Ansible still fits <a class="anchor" data-pagefind-ignore href="#where-ansible-still-fits" aria-label="Link to this section">#</a></h2>
<p>This isn&rsquo;t a takedown. We use Ansible too, for orchestration, one-off rollouts, and provisioning steps where an ordered, imperative run is exactly what you want. The distinction we draw: <strong>Ansible deploys, CFEngine maintains.</strong> For the job of keeping hundreds of hosts continuously correct with minimal overhead, CFEngine was the right call, and years of quiet nights due to self-repairs have confirmed it.</p>
<hr>
<p><em>Questions about configuration management for your own infrastructure? That&rsquo;s what we do. We build it, we run it, we manage it.</em></p>
]]></content:encoded></item><item><title>Automating iSCSI Multipathing with Ansible</title><link>https://blog.bsdserver.nl/automating-iscsi-multipathing-with-ansible/</link><guid isPermaLink="false">693b680679eb54000160a52b</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 00:55:34 +0000</pubDate><description>Multipathing (MPIO - Multipath I/O) is essential for high availability and performance in iSCSI storage environments.</description><category>Linux</category><category>Storage</category><category>iSCSI</category><category>Ansible</category><category>High availability</category><category>Automation</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/ansible-iscsi-multipathing.png" medium="image"/><content:encoded><![CDATA[<p>A single iSCSI connection is a single point of failure. One broken switch port or NIC, and the server loses its disk.</p>
<p>Multipathing (MPIO, Multipath I/O) connects the initiator to the target over two or more network paths and shows them as one disk. This post builds an Ansible role that installs the iSCSI and multipath tools, logs in over every path and combines them into one multipath device.</p>
<h2 id="why-use-multipathing">Why use multipathing? <a class="anchor" data-pagefind-ignore href="#why-use-multipathing" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Redundancy</strong>: if one network path fails, another takes over</li>
<li><strong>Load balancing</strong>: I/O is spread across all paths</li>
<li><strong>Higher bandwidth</strong>: more network interfaces, more throughput</li>
<li><strong>Automatic failover</strong>: no manual action when a path fails</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 the target has portals on two or more storage networks and the server needs its disk to survive a network failure.</li>
<li><strong>Skip it</strong> when there is only one network path. Multipath adds nothing then; the plain initiator setup from <a href="https://blog.bsdserver.nl/automating-iscsi-initiator-configuration-with-ansible/">Automating iSCSI Initiator Configuration with Ansible</a> is enough.</li>
</ul>
<p>Want to understand each step by hand first? See <a href="https://blog.bsdserver.nl/setting-up-iscsi-multipathing-manually-on-linux-2/">Setting Up iSCSI Multipathing Manually on Linux</a>.</p>
<h2 id="how-it-works">How it works <a class="anchor" data-pagefind-ignore href="#how-it-works" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Ansible role <code>iscsi_multipath</code></td>
					<td>Control machine</td>
					<td>Installs packages, renders configs, logs in to every portal.</td>
			</tr>
			<tr>
					<td><code>iscsid</code></td>
					<td>Initiator</td>
					<td>One iSCSI session per portal (path).</td>
			</tr>
			<tr>
					<td><code>multipathd</code></td>
					<td>Initiator</td>
					<td>Sees the same LUN on every path (same WWID) and combines the paths into one <code>mpatha</code> device.</td>
			</tr>
			<tr>
					<td>iSCSI target</td>
					<td>Storage server</td>
					<td>One portal per storage network, same LUN behind both.</td>
			</tr>
	</tbody>
</table>
<p>The flow: log in to portal 1 → <code>sdb</code> appears → log in to portal 2 → <code>sdc</code> appears → <code>multipathd</code> sees the same WWID on both → creates <code>/dev/mapper/mpatha</code> → you use only <code>mpatha</code>.</p>
<h2 id="the-role-iscsi_multipath">The role: iscsi_multipath <a class="anchor" data-pagefind-ignore href="#the-role-iscsi_multipath" aria-label="Link to this section">#</a></h2>
<p>The role:</p>
<ul>
<li>Installs the required packages</li>
<li>Configures <code>iscsid.conf</code> and <code>multipath.conf</code></li>
<li>Discovers the iSCSI targets on every portal</li>
<li>Logs in to every path</li>
<li>Keeps <code>multipathd</code> enabled and running</li>
</ul>
<h3 id="role-directory-structure">Role directory structure <a class="anchor" data-pagefind-ignore href="#role-directory-structure" aria-label="Link to this section">#</a></h3>
<p>A standard role layout; the files below fill <code>defaults</code>, <code>tasks</code>, <code>handlers</code> and <code>templates</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">iscsi_multipath/
</span></span><span class="line"><span class="cl">├── tasks/
</span></span><span class="line"><span class="cl">│   ├── main.yml
</span></span><span class="line"><span class="cl">├── handlers/
</span></span><span class="line"><span class="cl">│   ├── main.yml
</span></span><span class="line"><span class="cl">├── templates/
</span></span><span class="line"><span class="cl">│   ├── iscsid.conf.j2
</span></span><span class="line"><span class="cl">│   ├── multipath.conf.j2
</span></span><span class="line"><span class="cl">├── vars/
</span></span><span class="line"><span class="cl">│   ├── main.yml
</span></span><span class="line"><span class="cl">├── defaults/
</span></span><span class="line"><span class="cl">│   ├── main.yml
</span></span><span class="line"><span class="cl">├── meta/
</span></span><span class="line"><span class="cl">│   ├── main.yml
</span></span><span class="line"><span class="cl">├── README.md
</span></span></code></pre></div><h2 id="role-configuration">Role configuration <a class="anchor" data-pagefind-ignore href="#role-configuration" aria-label="Link to this section">#</a></h2>
<h3 id="define-variables">Define variables <a class="anchor" data-pagefind-ignore href="#define-variables" aria-label="Link to this section">#</a></h3>
<p><code>iscsi_target_ips</code> lists one portal per path; the role discovers and logs in to each. Create <code>defaults/main.yml</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">iscsi_target_ips</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="s2">&#34;192.168.2.253&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="s2">&#34;192.168.3.253&#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">iscsi_target_name</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;iqn.2025-03.com.example:storage&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">iscsi_chap_username</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ vault_iscsi_chap_username }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">iscsi_chap_password</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ vault_iscsi_chap_password }}&#34;</span><span class="w">
</span></span></span></code></pre></div><p>The CHAP credentials themselves don&rsquo;t belong in the role. Keep them in an Ansible Vault encrypted file next to your playbook and inventory, <code>group_vars/all/vault.yml</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">ansible-vault create group_vars/all/vault.yml
</span></span></code></pre></div><p>Ansible asks for a new vault password and opens your editor. Add the CHAP credentials, prefixed with <code>vault_</code> so it is obvious where they come from:</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">vault_iscsi_chap_username</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;your_username&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">vault_iscsi_chap_password</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;your_secure_password&#34;</span><span class="w">
</span></span></span></code></pre></div><ul>
<li>On disk the file starts with <code>$ANSIBLE_VAULT;1.1;AES256</code> and is safe to commit.</li>
<li>Already have a plaintext file? Encrypt it in place with <code>ansible-vault encrypt group_vars/all/vault.yml</code>.</li>
<li>Use <code>ansible-vault view</code> or <code>ansible-vault edit</code> to read or change it later.</li>
</ul>
<h3 id="tasks">Tasks <a class="anchor" data-pagefind-ignore href="#tasks" aria-label="Link to this section">#</a></h3>
<p>The tasks install the tools, write both configs, load the multipath config and then log in over every path. Create <code>tasks/main.yml</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="nn">---</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">Install iSCSI and multipath packages</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ansible.builtin.apt</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">name</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">open-iscsi</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">multipath-tools</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">present</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">update_cache</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl">- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Deploy iSCSI configuration</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ansible.builtin.template</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">src</span><span class="p">:</span><span class="w"> </span><span class="l">iscsid.conf.j2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">dest</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/iscsi/iscsid.conf</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">owner</span><span class="p">:</span><span class="w"> </span><span class="l">root</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">group</span><span class="p">:</span><span class="w"> </span><span class="l">root</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">mode</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;0644&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">no_log</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">  </span><span class="c"># the rendered file contains the CHAP password</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">name</span><span class="p">:</span><span class="w"> </span><span class="l">Deploy Multipath configuration</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ansible.builtin.template</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">src</span><span class="p">:</span><span class="w"> </span><span class="l">multipath.conf.j2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">dest</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/multipath.conf</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">owner</span><span class="p">:</span><span class="w"> </span><span class="l">root</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">group</span><span class="p">:</span><span class="w"> </span><span class="l">root</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">mode</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;0644&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">notify</span><span class="p">:</span><span class="w"> </span><span class="l">Reload multipathd</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">name</span><span class="p">:</span><span class="w"> </span><span class="l">Enable and start multipathd</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ansible.builtin.systemd</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">multipathd</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">started</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">enabled</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl">- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Load a changed multipath configuration before logging in</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ansible.builtin.meta</span><span class="p">:</span><span class="w"> </span><span class="l">flush_handlers</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">name</span><span class="p">:</span><span class="w"> </span><span class="l">Discover iSCSI targets</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ansible.builtin.command</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;iscsiadm -m discovery -t st -p {{ item }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">loop</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ iscsi_target_ips }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">register</span><span class="p">:</span><span class="w"> </span><span class="l">iscsi_discovery</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">changed_when</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="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Check active iSCSI sessions</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ansible.builtin.command</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;iscsiadm -m session&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">register</span><span class="p">:</span><span class="w"> </span><span class="l">iscsi_sessions</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">changed_when</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">failed_when</span><span class="p">:</span><span class="w"> </span><span class="l">iscsi_sessions.rc not in [0, 21] </span><span class="w"> </span><span class="c"># 21 = no active sessions</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">name</span><span class="p">:</span><span class="w"> </span><span class="l">Log in to iSCSI targets</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ansible.builtin.command</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;iscsiadm -m node -T {{ iscsi_target_name }} -p {{ item }} --login&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">loop</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ iscsi_target_ips }}&#34;</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">(item ~ &#39;:3260&#39;) not in iscsi_sessions.stdout</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">changed_when</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">  </span><span class="c"># only runs for portals without a session</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">name</span><span class="p">:</span><span class="w"> </span><span class="l">Ensure iSCSI login persists across reboots</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ansible.builtin.command</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;iscsiadm -m node -T {{ iscsi_target_name }} -p {{ item }} --op=update --name=node.startup --value=automatic&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">loop</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ iscsi_target_ips }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">changed_when</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="w">
</span></span></span></code></pre></div><table>
	<thead>
			<tr>
					<th>Task</th>
					<th>What it does</th>
					<th>Why</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Install packages</td>
					<td><code>open-iscsi</code> and <code>multipath-tools</code></td>
					<td>Initiator and multipath daemon.</td>
			</tr>
			<tr>
					<td>Deploy iSCSI configuration</td>
					<td>Renders <code>iscsid.conf</code></td>
					<td><code>no_log: true</code>: the file contains the CHAP password.</td>
			</tr>
			<tr>
					<td>Deploy Multipath configuration</td>
					<td>Renders <code>multipath.conf</code></td>
					<td>Triggers a reload of <code>multipathd</code> when it changes.</td>
			</tr>
			<tr>
					<td>Enable and start multipathd</td>
					<td>Starts the daemon, enables it at boot</td>
					<td>It must run before the paths appear.</td>
			</tr>
			<tr>
					<td><code>flush_handlers</code></td>
					<td>Runs the reload now</td>
					<td>The new <code>multipath.conf</code> is loaded before the logins.</td>
			</tr>
			<tr>
					<td>Discover iSCSI targets</td>
					<td>Discovery on every portal</td>
					<td>Creates a node record per path.</td>
			</tr>
			<tr>
					<td>Check active iSCSI sessions</td>
					<td>Lists sessions</td>
					<td>Exit code 21 means &ldquo;no sessions&rdquo;, not an error.</td>
			</tr>
			<tr>
					<td>Log in to iSCSI targets</td>
					<td>Logs in per portal</td>
					<td>Skipped for portals that already have a session.</td>
			</tr>
			<tr>
					<td>Ensure login persists</td>
					<td>Sets <code>node.startup</code> to <code>automatic</code> per portal</td>
					<td>All paths come back after a reboot.</td>
			</tr>
	</tbody>
</table>
<h3 id="handlers">Handlers <a class="anchor" data-pagefind-ignore href="#handlers" aria-label="Link to this section">#</a></h3>
<p>One handler: reload <code>multipathd</code> when its config changes. Create <code>handlers/main.yml</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="nn">---</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">Reload multipathd</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ansible.builtin.systemd</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">multipathd</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">reloaded</span><span class="w">
</span></span></span></code></pre></div><p>Why the handler and the session check matter:</p>
<ul>
<li><strong>Reload, not start.</strong> <code>multipathd</code> is normally already running, so <code>state: started</code> alone never loads a new <code>multipath.conf</code>. The handler reloads it when the template changes, and <code>flush_handlers</code> runs it before the logins.</li>
<li><strong>Skip existing sessions.</strong> <code>iscsiadm --login</code> fails with &ldquo;session already present&rdquo; on a second run. The session check skips portals that are already logged in.</li>
</ul>
<h2 id="templates-for-configuration-files">Templates for configuration files <a class="anchor" data-pagefind-ignore href="#templates-for-configuration-files" aria-label="Link to this section">#</a></h2>
<h3 id="templatesiscsidconfj2">templates/iscsid.conf.j2 <a class="anchor" data-pagefind-ignore href="#templatesiscsidconfj2" aria-label="Link to this section">#</a></h3>
<p>The initiator settings: start <code>iscsid</code> via its socket, log in automatically at boot, authenticate with CHAP, scan for LUNs after login.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-jinja" data-lang="jinja"><span class="line"><span class="cl"><span class="x">iscsid.startup = /bin/systemctl start iscsid.socket
</span></span></span><span class="line"><span class="cl"><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">node.startup = automatic
</span></span></span><span class="line"><span class="cl"><span class="x">node.leading_login = No
</span></span></span><span class="line"><span class="cl"><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">node.session.auth.authmethod = CHAP
</span></span></span><span class="line"><span class="cl"><span class="x">node.session.auth.username = </span><span class="cp">{{</span> <span class="nv">iscsi_chap_username</span> <span class="cp">}}</span><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">node.session.auth.password = </span><span class="cp">{{</span> <span class="nv">iscsi_chap_password</span> <span class="cp">}}</span><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">node.session.scan = auto
</span></span></span></code></pre></div><ul>
<li><code>node.startup = automatic</code>: log in to all discovered paths at boot.</li>
<li><code>node.session.auth.*</code>: CHAP with the credentials from the vault.</li>
<li><code>node.session.scan = auto</code>: scan for LUNs automatically after login.</li>
</ul>
<h3 id="templatesmultipathconfj2">templates/multipath.conf.j2 <a class="anchor" data-pagefind-ignore href="#templatesmultipathconfj2" aria-label="Link to this section">#</a></h3>
<p>This tells <code>multipathd</code> which devices to manage and how to use the paths:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-jinja" data-lang="jinja"><span class="line"><span class="cl"><span class="x">defaults {
</span></span></span><span class="line"><span class="cl"><span class="x">    user_friendly_names yes
</span></span></span><span class="line"><span class="cl"><span class="x">}
</span></span></span><span class="line"><span class="cl"><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">blacklist {
</span></span></span><span class="line"><span class="cl"><span class="x">    wwid &#34;.*&#34;
</span></span></span><span class="line"><span class="cl"><span class="x">}
</span></span></span><span class="line"><span class="cl"><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">blacklist_exceptions {
</span></span></span><span class="line"><span class="cl"><span class="x">    wwid &#34;</span><span class="cp">{{</span> <span class="nv">iscsi_wwid</span> <span class="cp">}}</span><span class="x">&#34;
</span></span></span><span class="line"><span class="cl"><span class="x">}
</span></span></span><span class="line"><span class="cl"><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">multipaths {
</span></span></span><span class="line"><span class="cl"><span class="x">    multipath {
</span></span></span><span class="line"><span class="cl"><span class="x">        wwid &#34;</span><span class="cp">{{</span> <span class="nv">iscsi_wwid</span> <span class="cp">}}</span><span class="x">&#34;
</span></span></span><span class="line"><span class="cl"><span class="x">        alias mpatha
</span></span></span><span class="line"><span class="cl"><span class="x">        path_grouping_policy &#34;multibus&#34;
</span></span></span><span class="line"><span class="cl"><span class="x">        path_selector &#34;round-robin 0&#34;
</span></span></span><span class="line"><span class="cl"><span class="x">        failback immediate
</span></span></span><span class="line"><span class="cl"><span class="x">        rr_weight priorities
</span></span></span><span class="line"><span class="cl"><span class="x">        no_path_retry 5
</span></span></span><span class="line"><span class="cl"><span class="x">    }
</span></span></span><span class="line"><span class="cl"><span class="x">}
</span></span></span></code></pre></div><table>
	<thead>
			<tr>
					<th>Setting</th>
					<th>What it does</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>user_friendly_names yes</code></td>
					<td>Names maps <code>mpathN</code> instead of by WWID.</td>
			</tr>
			<tr>
					<td><code>blacklist { wwid &quot;.*&quot; }</code> + <code>blacklist_exceptions</code></td>
					<td>Ignore every device except your iSCSI LUN. Keeps local disks out.</td>
			</tr>
			<tr>
					<td><code>alias mpatha</code></td>
					<td>Fixed name for this LUN: <code>/dev/mapper/mpatha</code>.</td>
			</tr>
			<tr>
					<td><code>path_grouping_policy &quot;multibus&quot;</code></td>
					<td>All paths in one group, so all of them carry I/O.</td>
			</tr>
			<tr>
					<td><code>path_selector &quot;round-robin 0&quot;</code></td>
					<td>Rotate I/O over the paths in the group.</td>
			</tr>
			<tr>
					<td><code>failback immediate</code></td>
					<td>Switch back to the preferred path group as soon as it is available again.</td>
			</tr>
			<tr>
					<td><code>rr_weight priorities</code></td>
					<td>Weight the round-robin by path priority.</td>
			</tr>
			<tr>
					<td><code>no_path_retry 5</code></td>
					<td>When all paths are down, queue I/O for 5 checker intervals, then fail it.</td>
			</tr>
	</tbody>
</table>
<p><strong>Note:</strong> Don&rsquo;t blacklist <code>devnode &quot;^sd[a-z]&quot;</code>: the iSCSI paths are <code>sdX</code> devices as well, and that rule makes multipathd drop the map. The <code>wwid &quot;.*&quot;</code> blacklist with an exception for your LUN keeps local disks out without hiding the iSCSI paths.</p>
<h3 id="finding-the-wwid">Finding the WWID <a class="anchor" data-pagefind-ignore href="#finding-the-wwid" aria-label="Link to this section">#</a></h3>
<p>The template needs the WWID (World Wide Identifier) of the LUN in <code>iscsi_wwid</code>. Retrieve it manually, on a node that is already logged in to the target:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo multipath -ll
</span></span></code></pre></div><p>The WWID is the value between brackets after the map name. Then add it as <code>iscsi_wwid</code> to <code>vars/main.yml</code>.</p>
<h2 id="running-the-ansible-playbook">Running the Ansible playbook <a class="anchor" data-pagefind-ignore href="#running-the-ansible-playbook" aria-label="Link to this section">#</a></h2>
<p>A playbook that applies the role to all hosts. Create <code>setup_iscsi_multipath.yml</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">name</span><span class="p">:</span><span class="w"> </span><span class="l">Setup iSCSI Multipathing</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">hosts</span><span class="p">:</span><span class="w"> </span><span class="l">all</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">become</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">roles</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="l">iscsi_multipath</span><span class="w">
</span></span></span></code></pre></div><p>Run the playbook and enter the vault password when asked:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">ansible-playbook -i inventory setup_iscsi_multipath.yml --ask-vault-pass
</span></span></code></pre></div><p>Or, for unattended runs, with a password file kept outside the repository:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">ansible-playbook -i inventory setup_iscsi_multipath.yml --vault-password-file ~/.vault_pass.txt
</span></span></code></pre></div><p>Thanks to <code>no_log: true</code> on the <code>iscsid.conf</code> task the CHAP password never shows up in the output, not even with <code>-v</code> or <code>--diff</code>.</p>
<h2 id="verifying-the-setup">Verifying the setup <a class="anchor" data-pagefind-ignore href="#verifying-the-setup" aria-label="Link to this section">#</a></h2>
<p>Check that there is one session per path and that both paths are part of one multipath device.</p>
<p><strong>Active iSCSI sessions</strong> (one line per portal):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo iscsiadm -m session
</span></span></code></pre></div><p>Expected output:</p>
<pre tabindex="0"><code>tcp: [1] 192.168.2.253:3260,1 iqn.2025-03.com.example:storage (non-flash)
tcp: [2] 192.168.3.253:3260,1 iqn.2025-03.com.example:storage (non-flash)
</code></pre><p><strong>Multipath devices:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo multipath -ll
</span></span></code></pre></div><p>Expected output:</p>
<pre tabindex="0"><code>mpatha (3600140547f55689de4b49c098d9b1a3c) dm-0 LIO-ORG,iscsi_target
size=20G features=&#39;1 queue_if_no_path&#39; hwhandler=&#39;1 alua&#39; wp=rw
`-+- policy=&#39;round-robin 0&#39; prio=50 status=active
  |- 2:0:0:0 sdb 8:16 active ready running
  `- 3:0:0:0 sdc 8:32 active ready running
</code></pre><p>What to look for:</p>
<ul>
<li><code>mpatha (3600…)</code>: the alias and the WWID.</li>
<li><code>policy='round-robin 0'</code>: both paths are in one group.</li>
<li><code>sdb</code> and <code>sdc</code> both <code>active ready running</code>: both paths work. A failed path shows as <code>failed faulty</code>.</li>
</ul>
<h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Cause / fix</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>multipath -ll</code> shows nothing</td>
					<td>WWID in <code>iscsi_wwid</code> does not match the LUN, so the blacklist hides it. Compare with <code>/lib/udev/scsi_id -g -u -d /dev/sdb</code>.</td>
			</tr>
			<tr>
					<td>Map disappears after a config change</td>
					<td>A <code>devnode &quot;^sd[a-z]&quot;</code> blacklist hides the iSCSI paths. Use the WWID blacklist.</td>
			</tr>
			<tr>
					<td>Only one path in the map</td>
					<td>Login to one portal failed. Check <code>iscsiadm -m session</code> and the network to that portal.</td>
			</tr>
			<tr>
					<td>New <code>multipath.conf</code> has no effect</td>
					<td><code>multipathd</code> was not reloaded. Run <code>systemctl reload multipathd</code>.</td>
			</tr>
			<tr>
					<td>&ldquo;session already present&rdquo;</td>
					<td>Already logged in. The role skips logged-in portals.</td>
			</tr>
	</tbody>
</table>
<h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<ul>
<li>Keep the CHAP credentials in Ansible Vault; <code>no_log: true</code> keeps them out of the output.</li>
<li><code>iscsid.conf</code> on each node holds the CHAP password in plaintext. Consider mode <code>0600</code>.</li>
<li>Put the storage networks on separate VLANs or switches, not on the client network.</li>
<li>Limit LUN access on the target to the expected initiator IQNs.</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-iscsi-multipath-ansible" rel="noopener">pderuiter/blog-iscsi-multipath-ansible</a>. It creates an iSCSI target with a portal on each of two storage networks and an initiator on Proxmox, and applies the <code>iscsi_multipath</code> role from this post with the CHAP secret in Ansible Vault; run <code>terraform apply</code> and then <code>ansible-playbook site.yml --ask-vault-pass</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>With this role every node:</p>
<ul>
<li>Logs in to the target over every path</li>
<li>Keeps its sessions across reboots</li>
<li>Uses one multipath device with failover and load balancing</li>
<li>Gets the same setup as every other node</li>
</ul>
<p>Use <code>/dev/mapper/mpatha</code>, never the <code>sdX</code> paths, for filesystems or LVM.</p>
]]></content:encoded></item><item><title>Automating iSCSI Initiator Configuration with Ansible</title><link>https://blog.bsdserver.nl/automating-iscsi-initiator-configuration-with-ansible/</link><guid isPermaLink="false">693b679079eb54000160a50c</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 00:53:36 +0000</pubDate><description>Setting up iSCSI storage manually across multiple servers can be time-consuming and error-prone.</description><category>Linux</category><category>Storage</category><category>iSCSI</category><category>Ansible</category><category>Automation</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/ansible-iscsi-initiator.png" medium="image"/><content:encoded><![CDATA[<p>Setting up iSCSI storage manually across multiple servers can be time-consuming and error-prone. One server with a copied IQN or a typo in the CHAP secret, and its login fails or, worse, it sees another server&rsquo;s disks.</p>
<p>This post builds one Ansible playbook that installs the iSCSI initiator, gives every node its own IQN, logs in to the target with CHAP and keeps the session across reboots. A second run changes nothing.</p>
<h2 id="why-automate-the-initiator">Why automate the initiator? <a class="anchor" data-pagefind-ignore href="#why-automate-the-initiator" aria-label="Link to this section">#</a></h2>
<p>iSCSI (Internet Small Computer System Interface) lets servers (initiators) use remote storage (targets) over the network as if it were a local disk. The playbook gives you:</p>
<ul>
<li><strong>Installed packages</strong>: <code>open-iscsi</code>, plus <code>multipath-tools</code> for later</li>
<li><strong>One standard <code>iscsid.conf</code></strong>: same timeouts and CHAP settings on every node</li>
<li><strong>A unique IQN per node</strong>: derived from the inventory name</li>
<li><strong>Automatic discovery and login</strong>: only when there is no session yet</li>
<li><strong>Persistent connections</strong>: the node logs in again after a reboot</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 more than one or two servers connect to the same iSCSI storage, or when you rebuild servers often.</li>
<li><strong>Skip it</strong> for a single test box. The manual <code>iscsiadm</code> commands are quicker than writing the inventory and vault.</li>
</ul>
<h2 id="how-it-works">How it works <a class="anchor" data-pagefind-ignore href="#how-it-works" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Ansible playbook</td>
					<td>Control machine</td>
					<td>Installs packages, renders the config files, runs <code>iscsiadm</code>.</td>
			</tr>
			<tr>
					<td>Ansible Vault file</td>
					<td>Control machine (in the repo)</td>
					<td>Holds the CHAP username and password, encrypted.</td>
			</tr>
			<tr>
					<td><code>iscsid</code></td>
					<td>Every initiator</td>
					<td>Reads the IQN and CHAP settings, manages the sessions.</td>
			</tr>
			<tr>
					<td>iSCSI target</td>
					<td>Storage server</td>
					<td>Exports the LUNs and checks the CHAP credentials.</td>
			</tr>
	</tbody>
</table>
<p>The flow: playbook → install packages → render <code>iscsid.conf</code> and <code>initiatorname.iscsi</code> → restart <code>iscsid</code> → discover targets → log in (if not logged in yet) → mark the node <code>automatic</code> for reboots.</p>
<h2 id="prerequisites">Prerequisites <a class="anchor" data-pagefind-ignore href="#prerequisites" aria-label="Link to this section">#</a></h2>
<ul>
<li>Ansible on your control machine.</li>
<li>The target iSCSI storage reachable from every node (TCP 3260).</li>
<li>A unique <strong>iSCSI initiator name (IQN)</strong> per server. The template below takes care of this.</li>
</ul>
<h3 id="variables">Variables <a class="anchor" data-pagefind-ignore href="#variables" aria-label="Link to this section">#</a></h3>
<p>The playbook needs the target address, the target IQN and the CHAP credentials. Define them in <code>group_vars/all/vars.yml</code>; the credentials only point to vault variables:</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">iscsi_target_ip</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;192.168.2.253&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">iscsi_target_name</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;iqn.2025-03.com.example:storage&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">iscsi_chap_username</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ vault_iscsi_chap_username }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">iscsi_chap_password</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ vault_iscsi_chap_password }}&#34;</span><span class="w">
</span></span></span></code></pre></div><h3 id="keep-the-chap-secret-in-ansible-vault">Keep the CHAP secret in Ansible Vault <a class="anchor" data-pagefind-ignore href="#keep-the-chap-secret-in-ansible-vault" aria-label="Link to this section">#</a></h3>
<p>The CHAP secret should not sit in plaintext in your repository. The real values live in an encrypted file next to <code>vars.yml</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">ansible-vault create group_vars/all/vault.yml
</span></span></code></pre></div><p>Ansible asks for a new vault password and opens your editor. Add the CHAP credentials, prefixed with <code>vault_</code> so it is obvious where they come from:</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">vault_iscsi_chap_username</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;your_username&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">vault_iscsi_chap_password</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;your_secure_password&#34;</span><span class="w">
</span></span></span></code></pre></div><ul>
<li>On disk the file starts with <code>$ANSIBLE_VAULT;1.1;AES256</code> and is safe to commit.</li>
<li>Already have a plaintext file? Encrypt it in place with <code>ansible-vault encrypt group_vars/all/vault.yml</code>.</li>
<li>Use <code>ansible-vault view</code> or <code>ansible-vault edit</code> to read or change it later.</li>
</ul>
<h2 id="the-ansible-playbook">The Ansible playbook <a class="anchor" data-pagefind-ignore href="#the-ansible-playbook" aria-label="Link to this section">#</a></h2>
<p>Create <code>setup_iscsi.yml</code>. It runs top to bottom, and every step is safe to repeat:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nn">---</span><span class="w">
</span></span></span><span class="line"><span class="cl">- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Configure iSCSI Initiator</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">hosts</span><span class="p">:</span><span class="w"> </span><span class="l">all</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">become</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">tasks</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Install iSCSI packages</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ansible.builtin.apt</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">name</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- <span class="l">open-iscsi</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- <span class="l">multipath-tools </span><span class="w"> </span><span class="c"># Optional for multipathing</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">present</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">update_cache</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Deploy iSCSI configuration file</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ansible.builtin.template</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">src</span><span class="p">:</span><span class="w"> </span><span class="l">templates/iscsid.conf.j2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">dest</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/iscsi/iscsid.conf</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">owner</span><span class="p">:</span><span class="w"> </span><span class="l">root</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">group</span><span class="p">:</span><span class="w"> </span><span class="l">root</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">mode</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;0644&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">no_log</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">  </span><span class="c"># the rendered file contains the CHAP password</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">notify</span><span class="p">:</span><span class="w"> </span><span class="l">Restart iscsid</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">name</span><span class="p">:</span><span class="w"> </span><span class="l">Set unique iSCSI initiator name</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ansible.builtin.template</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">src</span><span class="p">:</span><span class="w"> </span><span class="l">templates/initiatorname.iscsi.j2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">dest</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/iscsi/initiatorname.iscsi</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">owner</span><span class="p">:</span><span class="w"> </span><span class="l">root</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">group</span><span class="p">:</span><span class="w"> </span><span class="l">root</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">mode</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;0644&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">notify</span><span class="p">:</span><span class="w"> </span><span class="l">Restart iscsid</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">name</span><span class="p">:</span><span class="w"> </span><span class="l">Enable iSCSI services at boot</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ansible.builtin.systemd</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ item }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">enabled</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">loop</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span>- <span class="l">iscsid</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span>- <span class="l">open-iscsi</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">name</span><span class="p">:</span><span class="w"> </span><span class="l">Restart iscsid now so it picks up the new initiator name</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ansible.builtin.meta</span><span class="p">:</span><span class="w"> </span><span class="l">flush_handlers</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">name</span><span class="p">:</span><span class="w"> </span><span class="l">Discover iSCSI targets</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ansible.builtin.command</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">cmd</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;iscsiadm -m discovery -t st -p {{ iscsi_target_ip }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">register</span><span class="p">:</span><span class="w"> </span><span class="l">iscsi_discovery</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">changed_when</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">name</span><span class="p">:</span><span class="w"> </span><span class="l">Check active iSCSI sessions</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ansible.builtin.command</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">cmd</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;iscsiadm -m session&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">register</span><span class="p">:</span><span class="w"> </span><span class="l">iscsi_sessions</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">changed_when</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">failed_when</span><span class="p">:</span><span class="w"> </span><span class="l">iscsi_sessions.rc not in [0, 21] </span><span class="w"> </span><span class="c"># 21 = no active sessions</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">name</span><span class="p">:</span><span class="w"> </span><span class="l">Log in to iSCSI target</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ansible.builtin.command</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">cmd</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;iscsiadm -m node -T {{ iscsi_target_name }} -p {{ iscsi_target_ip }} --login&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">register</span><span class="p">:</span><span class="w"> </span><span class="l">iscsi_login</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">changed_when</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;&#39;successful&#39; in iscsi_login.stdout&#34;</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">(iscsi_target_ip ~ &#39;:3260&#39;) not in iscsi_sessions.stdout</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">name</span><span class="p">:</span><span class="w"> </span><span class="l">Set iSCSI login to persist across reboots</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ansible.builtin.command</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">cmd</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;iscsiadm -m node -T {{ iscsi_target_name }} -p {{ iscsi_target_ip }} --op=update --name=node.startup --value=automatic&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">changed_when</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">handlers</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">Restart iscsid</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ansible.builtin.systemd</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">iscsid</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">restarted</span><span class="w">
</span></span></span></code></pre></div><p>What each task does:</p>
<table>
	<thead>
			<tr>
					<th>Task</th>
					<th>What it does</th>
					<th>Why</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Install iSCSI packages</td>
					<td>Installs <code>open-iscsi</code> and <code>multipath-tools</code></td>
					<td><code>multipath-tools</code> is optional, only needed for multipathing.</td>
			</tr>
			<tr>
					<td>Deploy iSCSI configuration file</td>
					<td>Renders <code>iscsid.conf</code></td>
					<td><code>no_log: true</code> because the file contains the CHAP password.</td>
			</tr>
			<tr>
					<td>Set unique iSCSI initiator name</td>
					<td>Renders <code>initiatorname.iscsi</code></td>
					<td>Each node logs in with its own IQN.</td>
			</tr>
			<tr>
					<td>Enable iSCSI services at boot</td>
					<td>Enables <code>iscsid</code> and <code>open-iscsi</code></td>
					<td><code>open-iscsi</code> logs in to <code>automatic</code> nodes at boot.</td>
			</tr>
			<tr>
					<td><code>flush_handlers</code></td>
					<td>Runs the <code>iscsid</code> restart now, not at the end</td>
					<td>The login below must use the new IQN.</td>
			</tr>
			<tr>
					<td>Discover iSCSI targets</td>
					<td><code>iscsiadm -m discovery</code> (sendtargets)</td>
					<td>Creates the node records for the target.</td>
			</tr>
			<tr>
					<td>Check active iSCSI sessions</td>
					<td>Lists sessions</td>
					<td>Exit code 21 means &ldquo;no sessions&rdquo; and is not an error.</td>
			</tr>
			<tr>
					<td>Log in to iSCSI target</td>
					<td><code>iscsiadm --login</code></td>
					<td>Skipped when a session to the portal exists.</td>
			</tr>
			<tr>
					<td>Set iSCSI login to persist</td>
					<td>Sets <code>node.startup</code> to <code>automatic</code></td>
					<td>The node logs in again after a reboot.</td>
			</tr>
	</tbody>
</table>
<p>Two details matter:</p>
<ul>
<li><strong>Restart <code>iscsid</code>, not <code>open-iscsi</code>.</strong> The <code>iscsid</code> daemon reads the initiator name. If it is not restarted after the name changes, the login still uses the old IQN and the target rejects it.</li>
<li><strong>Log in only once.</strong> <code>iscsiadm --login</code> fails with &ldquo;session already present&rdquo; when you are already logged in. The <code>when:</code> condition skips the login if a session to the portal exists, which keeps a second run at <code>changed=0</code>.</li>
</ul>
<h2 id="template-files">Template files <a class="anchor" data-pagefind-ignore href="#template-files" aria-label="Link to this section">#</a></h2>
<h3 id="templatesiscsidconfj2"><code>templates/iscsid.conf.j2</code> <a class="anchor" data-pagefind-ignore href="#templatesiscsidconfj2" aria-label="Link to this section">#</a></h3>
<p>The daemon configuration: how to start <code>iscsid</code>, how to authenticate, and how fast to detect a broken connection.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-jinja" data-lang="jinja"><span class="line"><span class="cl"><span class="x">iscsid.startup = /bin/systemctl start iscsid.socket
</span></span></span><span class="line"><span class="cl"><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">node.startup = automatic
</span></span></span><span class="line"><span class="cl"><span class="x">node.leading_login = No
</span></span></span><span class="line"><span class="cl"><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">node.session.auth.authmethod = CHAP
</span></span></span><span class="line"><span class="cl"><span class="x">node.session.auth.chap_algs = SHA3-256,SHA256,SHA1,MD5
</span></span></span><span class="line"><span class="cl"><span class="x">node.session.auth.username = </span><span class="cp">{{</span> <span class="nv">iscsi_chap_username</span> <span class="cp">}}</span><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">node.session.auth.password = </span><span class="cp">{{</span> <span class="nv">iscsi_chap_password</span> <span class="cp">}}</span><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">node.session.timeo.replacement_timeout = 120
</span></span></span><span class="line"><span class="cl"><span class="x">node.conn[0].timeo.login_timeout = 15
</span></span></span><span class="line"><span class="cl"><span class="x">node.conn[0].timeo.logout_timeout = 15
</span></span></span><span class="line"><span class="cl"><span class="x">node.conn[0].timeo.noop_out_interval = 5
</span></span></span><span class="line"><span class="cl"><span class="x">node.conn[0].timeo.noop_out_timeout = 5
</span></span></span><span class="line"><span class="cl"><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">node.session.scan = auto
</span></span></span></code></pre></div><p>What the settings do:</p>
<ul>
<li><code>iscsid.startup</code>: how <code>iscsiadm</code> starts the daemon when it is not running (via the systemd socket).</li>
<li><code>node.startup = automatic</code>: log in to discovered targets automatically at boot.</li>
<li><code>node.session.auth.authmethod = CHAP</code>: require CHAP; the username and password come from the vault.</li>
<li><code>node.session.auth.chap_algs</code>: CHAP hash algorithms to offer, strongest first. MD5 stays at the end for older targets.</li>
<li><code>node.session.timeo.replacement_timeout = 120</code>: seconds to wait for a lost session to come back before I/O fails. Lower it when you use multipathing, so the other path takes over sooner.</li>
<li><code>node.conn[0].timeo.login_timeout</code> / <code>logout_timeout</code>: give up on a login or logout after 15 seconds.</li>
<li><code>noop_out_interval</code> / <code>noop_out_timeout</code>: send a ping (NOP-Out) every 5 seconds; no answer within 5 seconds marks the connection as failed.</li>
<li><code>node.session.scan = auto</code>: scan for LUNs automatically after login.</li>
</ul>
<h3 id="templatesinitiatornameiscsij2"><code>templates/initiatorname.iscsi.j2</code> <a class="anchor" data-pagefind-ignore href="#templatesinitiatornameiscsij2" aria-label="Link to this section">#</a></h3>
<p>One line: the IQN of this node, built from its inventory name.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-jinja" data-lang="jinja"><span class="line"><span class="cl"><span class="x">InitiatorName=iqn.2025-03.com.example:</span><span class="cp">{{</span> <span class="nv">inventory_hostname</span> <span class="cp">}}</span><span class="x">
</span></span></span></code></pre></div><p>This ensures each node has a <strong>unique IQN</strong>, preventing conflicts in iSCSI authentication and LUN masking on the target.</p>
<h2 id="running-the-playbook">Running the playbook <a class="anchor" data-pagefind-ignore href="#running-the-playbook" aria-label="Link to this section">#</a></h2>
<p>Run it against the inventory that lists all nodes that need iSCSI, and enter the vault password when asked:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">ansible-playbook -i inventory setup_iscsi.yml --ask-vault-pass
</span></span></code></pre></div><p>For unattended runs (CI, cron), point Ansible at a password file instead. Keep it outside the repository with mode <code>0600</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">ansible-playbook -i inventory setup_iscsi.yml --vault-password-file ~/.vault_pass.txt
</span></span></code></pre></div><p>The <code>no_log: true</code> on the <code>iscsid.conf</code> task keeps the rendered CHAP password out of the output, also when you run with <code>-v</code> or <code>--diff</code>.</p>
<h2 id="verification">Verification <a class="anchor" data-pagefind-ignore href="#verification" aria-label="Link to this section">#</a></h2>
<p>Check on a node that the session is up, the LUN is visible and the login survives a reboot.</p>
<p><strong>Active sessions</strong> (one line per target portal):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo iscsiadm -m session
</span></span></code></pre></div><p>Expected output:</p>
<pre tabindex="0"><code>tcp: [1] 192.168.2.253:3260,1 iqn.2025-03.com.example:storage (non-flash)
</code></pre><p><strong>Attached LUNs</strong> (the iSCSI disk shows up as a new <code>sdX</code> device):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">lsblk
</span></span></code></pre></div><p><strong>Automatic login persists</strong> (the node record should contain <code>node.startup = automatic</code>):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo cat /etc/iscsi/nodes/iqn.2025-03.com.example:storage/192.168.2.253,3260,1/default
</span></span></code></pre></div><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Cause / fix</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Login fails with an authorization error</td>
					<td>Wrong CHAP credentials, or the target does not know this IQN yet. Check the vault values and the target ACL.</td>
			</tr>
			<tr>
					<td>Login still uses the old IQN</td>
					<td><code>iscsid</code> was not restarted after the name changed. Restart <code>iscsid</code>.</td>
			</tr>
			<tr>
					<td>&ldquo;session already present&rdquo;</td>
					<td>You are already logged in. The playbook skips the login in that case.</td>
			</tr>
			<tr>
					<td>Session up but no new disk in <code>lsblk</code></td>
					<td>The target does not map a LUN to this IQN. Check the LUN mapping on the target.</td>
			</tr>
			<tr>
					<td>No session after a reboot</td>
					<td><code>node.startup</code> is not <code>automatic</code>, or <code>open-iscsi</code> is not enabled.</td>
			</tr>
	</tbody>
</table>
<h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<ul>
<li>Keep the CHAP credentials in Ansible Vault, never in plaintext <code>group_vars</code>.</li>
<li><code>no_log: true</code> keeps the rendered password out of logs and <code>--diff</code> output.</li>
<li><code>iscsid.conf</code> contains the CHAP password in plaintext on each node. Consider mode <code>0600</code> for it.</li>
<li>Restrict LUN access on the target to the expected IQNs.</li>
<li>Keep iSCSI traffic on a dedicated storage network.</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-iscsi-initiator-ansible" rel="noopener">pderuiter/blog-iscsi-initiator-ansible</a>. It creates an iSCSI target and an initiator on Proxmox, adds an <code>iscsi_target</code> role so you can build both ends, and runs the playbook from this post as the <code>iscsi_initiator</code> role with the CHAP secret in Ansible Vault; run <code>terraform apply</code> and then <code>ansible-playbook site.yml --ask-vault-pass</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>With one playbook, every node gets:</p>
<ul>
<li>A unique IQN</li>
<li>CHAP authentication with the secret in Ansible Vault</li>
<li>iSCSI sessions that persist across reboots</li>
<li>The same storage setup as every other node</li>
</ul>
<p>A second run changes nothing, so you can run it on every deploy. Need more than one path to the storage? Continue with <a href="https://blog.bsdserver.nl/automating-iscsi-multipathing-with-ansible/">Automating iSCSI Multipathing with Ansible</a>.</p>
]]></content:encoded></item><item><title>MySQL Backup with Ansible</title><link>https://blog.bsdserver.nl/mysql-backup-with-ansible/</link><guid isPermaLink="false">693b51f179eb54000160a4ac</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Thu, 11 Dec 2025 23:21:21 +0000</pubDate><description>MySQL Backup with Ansible As someone with a lot of technical knowledge, I sometimes forget the finer details, like specific command-line options.</description><category>Automation</category><category>MySQL</category><category>Ansible</category><category>Backup</category><category>DevOps</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/mysql-backup-ansible.png" medium="image"/><content:encoded><![CDATA[<p>Taking a MySQL backup by hand means remembering the right <code>mysqldump</code> options, the compression step and the copy to another server. Forget one detail and you end up with an empty or missing backup.</p>
<p>I put tasks like this in small Ansible playbooks. This one dumps a MySQL database, compresses it with gzip, and copies it to a backup server with rsync over SSH.</p>
<h2 id="why-a-playbook">Why a playbook? <a class="anchor" data-pagefind-ignore href="#why-a-playbook" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>No forgotten options</strong>: the exact commands are written down once.</li>
<li><strong>Consistency</strong>: every run does the same steps, in the same order.</li>
<li><strong>Shareable</strong>: anyone in the team can run the same backup without missing a step.</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 ad-hoc backups before a change, or as a simple scheduled backup of a small database.</li>
<li><strong>Skip it</strong> for large databases or point-in-time recovery; a logical dump of the whole database every run does not scale there.</li>
</ul>
<h2 id="how-it-works">How it works <a class="anchor" data-pagefind-ignore href="#how-it-works" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Play 1: dump</td>
					<td>MySQL server (<code>mysql</code> group)</td>
					<td>Runs <code>mysqldump</code>, compresses to <code>/tmp/backup/&lt;database&gt;.sql.gz</code>.</td>
			</tr>
			<tr>
					<td>Play 2: copy</td>
					<td>Backup server (<code>backup</code> group), delegated to the MySQL server</td>
					<td>rsync pushes <code>/tmp/backup/</code> to the backup server.</td>
			</tr>
	</tbody>
</table>
<p>The flow: <code>mysqldump</code> → <code>gzip</code> → <code>/tmp/backup</code> on the MySQL server → rsync over SSH → <code>backup_dest</code> on the backup server.</p>
<h2 id="the-playbook">The Playbook <a class="anchor" data-pagefind-ignore href="#the-playbook" aria-label="Link to this section">#</a></h2>
<p>Two plays: the first creates the dump on the MySQL server, the second copies it off the server.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nn">---</span><span class="w">
</span></span></span><span class="line"><span class="cl">- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Backup MySQL server</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">hosts</span><span class="p">:</span><span class="w"> </span><span class="l">mysql</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">become</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">tasks</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Create backup directory</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ansible.builtin.file</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="l">/tmp/backup</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">directory</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">mode</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;0755&#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="w">    </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Dump MySQL database</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ansible.builtin.shell</span><span class="p">:</span><span class="w"> </span><span class="p">&gt;-</span><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">        set -o pipefail &amp;&amp;
</span></span></span><span class="line"><span class="cl"><span class="sd">        mysqldump -u{{ mysql_user }} -p{{ mysql_password | quote }} {{ mysql_database }}
</span></span></span><span class="line"><span class="cl"><span class="sd">        | gzip &gt; /tmp/backup/{{ mysql_database }}.sql.gz</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">args</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">executable</span><span class="p">:</span><span class="w"> </span><span class="l">/bin/bash</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">changed_when</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl">- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Copy backup to the backup server</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">hosts</span><span class="p">:</span><span class="w"> </span><span class="l">backup</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">gather_facts</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">tasks</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">Copy backup to remote server</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ansible.posix.synchronize</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">src</span><span class="p">:</span><span class="w"> </span><span class="l">/tmp/backup/</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">dest</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ backup_dest }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">private_key</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ ssh_key }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">delegate_to</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ groups[&#39;mysql&#39;][0] }}&#34;</span><span class="w">
</span></span></span></code></pre></div><h3 id="the-dump-task">The dump task <a class="anchor" data-pagefind-ignore href="#the-dump-task" aria-label="Link to this section">#</a></h3>
<ul>
<li><code>mysqldump ... | gzip</code>: dumps one database and compresses it on the fly. Each run overwrites <code>/tmp/backup/&lt;database&gt;.sql.gz</code>.</li>
<li><code>set -o pipefail</code>: makes the task fail when <code>mysqldump</code> fails (for example on a wrong password). Without it the pipe returns gzip&rsquo;s exit code and you silently end up with an empty backup.</li>
<li><code>executable: /bin/bash</code>: <code>pipefail</code> is a bash option; the default <code>/bin/sh</code> may not support it.</li>
<li><code>mysql_password | quote</code>: escapes the password for the shell, so special characters don&rsquo;t break the command.</li>
<li><code>changed_when: true</code>: a new dump is always a change.</li>
</ul>
<h3 id="the-copy-task">The copy task <a class="anchor" data-pagefind-ignore href="#the-copy-task" aria-label="Link to this section">#</a></h3>
<p><code>synchronize</code> always copies from the host it runs on to the inventory host. So the second play targets the backup server and delegates the task to the MySQL server:</p>
<ul>
<li>rsync runs on the MySQL server and pushes <code>/tmp/backup/</code> to the backup server.</li>
<li>It connects as the backup server&rsquo;s <code>ansible_user</code>, with the <code>private_key</code> you specify.</li>
</ul>
<h2 id="variables">Variables <a class="anchor" data-pagefind-ignore href="#variables" aria-label="Link to this section">#</a></h2>
<p>Before running the playbook, you&rsquo;ll need to update the following variables with the appropriate values:</p>
<table>
	<thead>
			<tr>
					<th>Variable</th>
					<th>What it is</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>mysql_user</code></td>
					<td>The MySQL user with permissions to perform the backup.</td>
			</tr>
			<tr>
					<td><code>mysql_password</code></td>
					<td>The password for the MySQL user.</td>
			</tr>
			<tr>
					<td><code>mysql_database</code></td>
					<td>The name of the MySQL database you want to back up.</td>
			</tr>
			<tr>
					<td><code>backup_dest</code></td>
					<td>The path on the remote server where the backup file will be copied.</td>
			</tr>
			<tr>
					<td><code>backup_user</code></td>
					<td>The username for the remote server. Set it as <code>ansible_user</code> on the backup server in your inventory (e.g. <code>backup01 ansible_user=&quot;{{ backup_user }}&quot;</code>); <code>remote_user</code> is a reserved name in Ansible and the <code>synchronize</code> module has no such option.</td>
			</tr>
			<tr>
					<td><code>ssh_key</code></td>
					<td>The path, on the MySQL server, of the SSH key used to connect to the remote server.</td>
			</tr>
	</tbody>
</table>
<blockquote>
<p><strong>Note:</strong> Don&rsquo;t put credentials in a plaintext readable file. Put them in Ansible Vault instead!</p>
</blockquote>
<h2 id="running-the-playbook">Running the Playbook <a class="anchor" data-pagefind-ignore href="#running-the-playbook" aria-label="Link to this section">#</a></h2>
<p>To run the playbook, use the following command:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">ansible-playbook -i &lt;inventory_file&gt; playbook.yml
</span></span></code></pre></div><p>Where <code>&lt;inventory_file&gt;</code> is the file listing your target servers (a <code>mysql</code> group and a <code>backup</code> group), and <code>playbook.yml</code> is the name of your playbook.</p>
<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>Vault the credentials</strong>: <code>mysql_password</code> and the backup user belong in Ansible Vault.</li>
<li><strong>Password on the command line</strong>: <code>-p&lt;password&gt;</code> is visible in the process list while the dump runs. A MySQL option file avoids that.</li>
<li><strong>Backup file permissions</strong>: <code>/tmp/backup</code> is mode <code>0755</code>, so local users can read the dump. Tighten it on shared servers.</li>
<li><strong>SSH key scope</strong>: the key on the MySQL server only needs write access to <code>backup_dest</code>.</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-mysql-backup" rel="noopener">pderuiter/blog-mysql-backup</a>. It creates a MySQL server and a backup server on Proxmox and runs this playbook as roles; fill in <code>terraform.tfvars</code> and the vault, then run <code>terraform apply</code> and <code>ansible-playbook site.yml</code>.</p>
<h2 id="before-you-rely-on-it">Before You Rely On It <a class="anchor" data-pagefind-ignore href="#before-you-rely-on-it" aria-label="Link to this section">#</a></h2>
<ul>
<li>Test the playbook in a non-production environment first, including a restore: a backup you never restored is not a backup.</li>
<li>Make sure the remote server has enough storage space for the backups.</li>
<li>Make sure you have permission to write to the destination directory.</li>
</ul>
]]></content:encoded></item><item><title>Automatic Disk Decryption with Tang</title><link>https://blog.bsdserver.nl/automatic-disk-decryption-with-tang/</link><guid isPermaLink="false">693b4fc079eb54000160a43d</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Thu, 11 Dec 2025 23:12:00 +0000</pubDate><description>If you're setting up disk encryption on your Red Hat Enterprise Linux 9 (RHEL9) servers, using a Tang server can be a smart choice to streamline the…</description><category>Linux</category><category>Security</category><category>Ansible</category><category>RHEL</category><category>Encryption</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/linux-tang-disk-decryption.png" medium="image"/><content:encoded><![CDATA[<p>If you&rsquo;re setting up disk encryption on your Red Hat Enterprise Linux 9 (RHEL9) servers, every reboot asks for a passphrase. In a server farm that means someone at a console for each reboot, which makes automated restarts and patching impractical.</p>
<p>This post deploys a Tang server with Ansible and configures RHEL9 clients through Kickstart, so encrypted volumes unlock automatically at boot as long as the Tang server is reachable.</p>
<h2 id="why-tang">Why Tang? <a class="anchor" data-pagefind-ignore href="#why-tang" aria-label="Link to this section">#</a></h2>
<p>Encryption at rest keeps data unreadable when a disk or server is stolen. Tang removes the operational cost of it:</p>
<ul>
<li><strong>Unattended reboots</strong> - Clients unlock their LUKS volumes over the network, no passphrase typed.</li>
<li><strong>Location-bound unlocking</strong> - A disk only unlocks while it can reach your Tang server. Taken out of the network, it stays locked.</li>
<li><strong>Lightweight</strong> - Tang is a small HTTP service with nothing to manage per client.</li>
<li><strong>Repeatable</strong> - Ansible sets up the server, Kickstart sets up the clients, so every machine is configured the same way.</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> for encrypted servers in a data centre or edge location that must reboot without someone typing a passphrase.</li>
<li><strong>Skip it</strong> for a single machine you reboot by hand, or a machine that is not on a trusted network at boot (a laptop). A passphrase or TPM is simpler there.</li>
</ul>
<h2 id="how-it-works">How It Works <a class="anchor" data-pagefind-ignore href="#how-it-works" aria-label="Link to this section">#</a></h2>
<p>Tang works together with Clevis, the client-side tool that hooks into LUKS.</p>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Tang (<code>tangd.socket</code>)</td>
					<td>Tang server</td>
					<td>Answers Clevis requests over HTTP so the client can recover its key.</td>
			</tr>
			<tr>
					<td>Clevis + <code>clevis-dracut</code></td>
					<td>Each encrypted client</td>
					<td>Binds the LUKS volume to Tang and contacts Tang from the initramfs at boot.</td>
			</tr>
			<tr>
					<td>LUKS</td>
					<td>Each encrypted client</td>
					<td>The disk encryption itself. The original passphrase keeps working as a fallback.</td>
			</tr>
	</tbody>
</table>
<p>The flow: client boots → initramfs brings up the network → Clevis contacts Tang → the LUKS key is recovered → the volume unlocks → boot continues.</p>
<h2 id="prerequisites">Prerequisites <a class="anchor" data-pagefind-ignore href="#prerequisites" aria-label="Link to this section">#</a></h2>
<ol>
<li><strong>Red Hat Enterprise Linux 9 (RHEL9) Server</strong>: This tutorial assumes that you are using RHEL9. Make sure the system is installed and configured.</li>
<li><strong>Root or Sudo Access</strong>: You will need root privileges to install packages and configure services.</li>
<li><strong>Ansible Installed</strong>: Ansible should be installed on the control node to automate the deployment process.</li>
<li><strong>FirewallD Installed and Configured</strong>: The playbook assumes you are using FirewallD for managing firewall rules.</li>
<li><strong>Network Connectivity</strong>: Ensure that the Tang server and any client machines can communicate over the network.</li>
<li><strong>Clevis Installed on Clients</strong>: If you plan to use Tang to automate decryption, Clevis must be installed on the client systems.</li>
</ol>
<h2 id="deploying-the-tang-server-with-ansible">Deploying the Tang Server with Ansible <a class="anchor" data-pagefind-ignore href="#deploying-the-tang-server-with-ansible" aria-label="Link to this section">#</a></h2>
<p>Setting up Tang by hand is quick, but you want more than one Tang server for redundancy. A playbook keeps them identical.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl">- <span class="nt">hosts</span><span class="p">:</span><span class="w"> </span><span class="l">tang_server</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">become</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">tasks</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># Install packages required for Tang server</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Install required packages for Tang server</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ansible.builtin.package</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">name</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- <span class="l">tang</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- <span class="l">httpd</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">present</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># Configure firewall rules for Tang server</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Configure firewall for Tang server</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ansible.posix.firewalld</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">service</span><span class="p">:</span><span class="w"> </span><span class="l">http</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">permanent</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">enabled</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">immediate</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># Start and enable Tang server</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Start and enable Tang server</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">ansible.builtin.systemd</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">tangd.socket</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">enabled</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">started</span><span class="w">
</span></span></span></code></pre></div><p>What each task does:</p>
<ul>
<li><strong>Install packages</strong>: installs <code>tang</code> (and <code>httpd</code>).</li>
<li><strong>Firewall</strong>: Tang talks plain HTTP, so the <code>http</code> service (port 80) is opened. <code>immediate: true</code> applies the rule now as well as permanently, without a separate reload.</li>
<li><strong><code>tangd.socket</code></strong>: socket activation. systemd listens on the port and starts Tang per request; <code>enabled: true</code> makes it survive reboots.</li>
</ul>
<h2 id="configuring-the-clients-with-kickstart">Configuring the Clients with Kickstart <a class="anchor" data-pagefind-ignore href="#configuring-the-clients-with-kickstart" aria-label="Link to this section">#</a></h2>
<p>The client side is done at install time: encrypt the volume, install Clevis, and bind the volume to Tang.</p>
<h3 id="finding-the-luks-volume-uuid">Finding the LUKS Volume UUID <a class="anchor" data-pagefind-ignore href="#finding-the-luks-volume-uuid" aria-label="Link to this section">#</a></h3>
<p>You need to know which LUKS volume to bind. To look it up during the Kickstart installation:</p>
<ol>
<li><strong>Open a terminal</strong>: press <code>Ctrl+Alt+F2</code> during the installation.</li>
<li><strong>Find the partition</strong>: run <code>lsblk</code> and locate the encrypted device (e.g. <code>/dev/sda3</code>).</li>
<li><strong>Read its UUID</strong>:</li>
</ol>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo cryptsetup luksUUID /dev/sda3
</span></span></code></pre></div><p>Replace <code>/dev/sda3</code> with your device. The output is the <code>volume-UUID</code> of that LUKS partition, which identifies the volume in your Kickstart configuration.</p>
<h3 id="the-kickstart-snippet">The Kickstart Snippet <a class="anchor" data-pagefind-ignore href="#the-kickstart-snippet" aria-label="Link to this section">#</a></h3>
<p>This snippet installs Clevis, creates the encrypted volume and binds it to Tang in one installation run.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Install Clevis for client-side automation</span>
</span></span><span class="line"><span class="cl">%packages
</span></span><span class="line"><span class="cl">@core
</span></span><span class="line"><span class="cl">clevis
</span></span><span class="line"><span class="cl">clevis-dracut
</span></span><span class="line"><span class="cl">%end
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Partition and encrypt the logical volume</span>
</span></span><span class="line"><span class="cl">part pv.01 --size<span class="o">=</span><span class="m">1</span> --grow --encrypted --passphrase<span class="o">=</span>&lt;dummy-passphrase&gt;
</span></span><span class="line"><span class="cl">volgroup vg01 pv.01
</span></span><span class="line"><span class="cl">logvol / --fstype<span class="o">=</span><span class="s2">&#34;ext4&#34;</span> --name<span class="o">=</span>root --vgname<span class="o">=</span>vg01 --size<span class="o">=</span><span class="m">20480</span> --encrypted --passphrase<span class="o">=</span>&lt;dummy-passphrase&gt;
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Set up Clevis to use Tang for decryption</span>
</span></span><span class="line"><span class="cl">%post
</span></span><span class="line"><span class="cl"><span class="c1"># Bind the LUKS volume to Tang server for automatic decryption</span>
</span></span><span class="line"><span class="cl">clevis luks <span class="nb">bind</span> -d /dev/mapper/vg01-root tang <span class="s1">&#39;{&#34;url&#34;: &#34;http://&lt;Tang-server-IP&gt;:80&#34;}&#39;</span>
</span></span><span class="line"><span class="cl">%end
</span></span></code></pre></div><table>
	<thead>
			<tr>
					<th>Section</th>
					<th>What it does</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>%packages</code></td>
					<td><code>clevis</code> for binding, <code>clevis-dracut</code> so the initramfs can unlock at boot.</td>
			</tr>
			<tr>
					<td><code>part</code> / <code>volgroup</code> / <code>logvol</code></td>
					<td>Creates the encrypted volume with a temporary passphrase. Replace it after installation.</td>
			</tr>
			<tr>
					<td><code>%post</code></td>
					<td><code>clevis luks bind</code> adds a Tang-based key to the LUKS volume. From then on, boot unlocks it via Tang.</td>
			</tr>
	</tbody>
</table>
<h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Keep the passphrase.</strong> The <code>&lt;dummy-passphrase&gt;</code> stays a valid key. Change it to a strong one and store it safely; it is your fallback when Tang is unreachable.</li>
<li><strong>Tang reachable = disk unlockable.</strong> Anyone with the disk and network access to Tang can unlock it. Only expose Tang on the internal network where your servers boot.</li>
<li><strong>Run more than one Tang server.</strong> If the only Tang server is down, clients wait for the passphrase at boot.</li>
</ul>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>With a few lines of Ansible you have a Tang server, and with a Kickstart snippet every new client binds to it at install time. Encrypted servers can then reboot unattended, whether you run a handful or hundreds.</p>
<p>Give this Ansible playbook a try, and let me know how it works for you! If you have any questions or run into any challenges, feel free to leave a comment.</p>
]]></content:encoded></item></channel></rss>