<?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>iSCSI | A DevOps Blog</title><link>https://blog.bsdserver.nl/tag/iscsi/</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/iscsi/rss/" rel="self" type="application/rss+xml"/><ttl>60</ttl><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>Setting Up iSCSI Multipathing Manually on Linux</title><link>https://blog.bsdserver.nl/setting-up-iscsi-multipathing-manually-on-linux-2/</link><guid isPermaLink="false">693b67e379eb54000160a523</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 00:54:59 +0000</pubDate><description>Multipathing (MPIO - Multipath I/O) is crucial for high availability and performance in iSCSI storage environments.</description><category>Linux</category><category>Storage</category><category>iSCSI</category><category>High availability</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/iscsi-multipathing.png" medium="image"/><content:encoded><![CDATA[<p>A server with one iSCSI connection loses its disk when that one network path fails. A switch reboot or a bad cable is enough.</p>
<p>Multipathing (MPIO, Multipath I/O) connects the server (initiator) to the storage (target) over two or more networks and shows the paths as one disk. This post configures iSCSI multipathing by hand on Linux, without Ansible, and tests the failover.</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 the paths</li>
<li><strong>Higher bandwidth</strong>: more network interfaces, more throughput</li>
<li><strong>Failover support</strong>: storage stays available while a path is down</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 storage has two separate networks and the server must survive losing one.</li>
<li><strong>Skip it</strong> with a single network path; a plain iSCSI login is enough.</li>
<li><strong>Do it by hand</strong> to learn the steps or for one server. For more servers, see <a href="https://blog.bsdserver.nl/automating-iscsi-multipathing-with-ansible/">Automating iSCSI Multipathing with Ansible</a>.</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>iSCSI target</td>
					<td>Storage server</td>
					<td>Exports the LUN on two IP addresses (portals).</td>
			</tr>
			<tr>
					<td><code>iscsid</code></td>
					<td>Initiator</td>
					<td>One session per portal; each session shows the LUN as its own <code>sdX</code> device.</td>
			</tr>
			<tr>
					<td><code>multipathd</code></td>
					<td>Initiator</td>
					<td>Sees that <code>sdb</code> and <code>sdc</code> have the same WWID and combines them into <code>/dev/mapper/mpatha</code>.</td>
			</tr>
	</tbody>
</table>
<p>The flow: discover the target → log in over path 1 (<code>sdb</code>) and path 2 (<code>sdc</code>) → <code>multipathd</code> matches the WWID → <code>mpatha</code> → filesystem or LVM on <code>mpatha</code>.</p>
<h2 id="requirements">Requirements <a class="anchor" data-pagefind-ignore href="#requirements" aria-label="Link to this section">#</a></h2>
<h3 id="server-side-iscsi-target">Server side (iSCSI target) <a class="anchor" data-pagefind-ignore href="#server-side-iscsi-target" aria-label="Link to this section">#</a></h3>
<ul>
<li>The target must support multiple network paths.</li>
<li>Each LUN must be accessible via <strong>at least two separate IP addresses</strong>.</li>
<li>Example target setup:</li>
</ul>
<pre tabindex="0"><code>iSCSI Target:
IP1: 192.168.2.253 (eth1)
IP2: 192.168.3.253 (eth2)
</code></pre><h3 id="client-side-iscsi-initiator">Client side (iSCSI initiator) <a class="anchor" data-pagefind-ignore href="#client-side-iscsi-initiator" aria-label="Link to this section">#</a></h3>
<ul>
<li>Multiple network interfaces, one per storage network.</li>
<li>The <code>open-iscsi</code> and <code>multipath-tools</code> packages installed.</li>
<li>Two or more iSCSI sessions to the same LUN using different IPs.</li>
</ul>
<h2 id="install-required-packages">Install required packages <a class="anchor" data-pagefind-ignore href="#install-required-packages" aria-label="Link to this section">#</a></h2>
<p><code>open-iscsi</code> provides the initiator, <code>multipath-tools</code> the multipath daemon. On the iSCSI initiator (client):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo apt update
</span></span><span class="line"><span class="cl">sudo apt install -y open-iscsi multipath-tools
</span></span></code></pre></div><p>Start both daemons now and at boot:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo systemctl <span class="nb">enable</span> --now iscsid multipathd
</span></span></code></pre></div><h2 id="discover-and-log-in-to-iscsi-targets">Discover and log in to iSCSI targets <a class="anchor" data-pagefind-ignore href="#discover-and-log-in-to-iscsi-targets" aria-label="Link to this section">#</a></h2>
<h3 id="discover-available-targets">Discover available targets <a class="anchor" data-pagefind-ignore href="#discover-available-targets" aria-label="Link to this section">#</a></h3>
<p>Discovery (<code>-t st</code>, SendTargets) asks the target which portals and IQNs it offers and stores them as node records. Run it for each target IP. Each discovery returns every portal the target advertises, so both commands print the same two lines:</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 discovery -t st -p 192.168.2.253
</span></span><span class="line"><span class="cl">sudo iscsiadm -m discovery -t st -p 192.168.3.253
</span></span></code></pre></div><p>Expected output:</p>
<pre tabindex="0"><code>192.168.2.253:3260,1 iqn.2025-03.com.example:storage
192.168.3.253:3260,1 iqn.2025-03.com.example:storage
</code></pre><h3 id="log-in-to-both-paths">Log in to both paths <a class="anchor" data-pagefind-ignore href="#log-in-to-both-paths" aria-label="Link to this section">#</a></h3>
<p>One login per portal gives one session, and one <code>sdX</code> device, per path:</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 node -T iqn.2025-03.com.example:storage -p 192.168.2.253 --login
</span></span><span class="line"><span class="cl">sudo iscsiadm -m node -T iqn.2025-03.com.example:storage -p 192.168.3.253 --login
</span></span></code></pre></div><p>Verify active iSCSI sessions:</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>Set the login to persist across reboots, for both paths. <code>node.startup=automatic</code> makes the initiator log in again at boot:</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 node -T iqn.2025-03.com.example:storage -p 192.168.2.253 --op<span class="o">=</span>update --name<span class="o">=</span>node.startup --value<span class="o">=</span>automatic
</span></span><span class="line"><span class="cl">sudo iscsiadm -m node -T iqn.2025-03.com.example:storage -p 192.168.3.253 --op<span class="o">=</span>update --name<span class="o">=</span>node.startup --value<span class="o">=</span>automatic
</span></span></code></pre></div><h2 id="configure-multipathing">Configure multipathing <a class="anchor" data-pagefind-ignore href="#configure-multipathing" aria-label="Link to this section">#</a></h2>
<h3 id="enable-multipath">Enable multipath <a class="anchor" data-pagefind-ignore href="#enable-multipath" aria-label="Link to this section">#</a></h3>
<p><code>/etc/multipath.conf</code> tells <code>multipathd</code> which devices to combine and how to use the paths. Edit the file:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo nano /etc/multipath.conf
</span></span></code></pre></div><p>Add the following configuration:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-ini" data-lang="ini"><span class="line"><span class="cl"><span class="na">defaults {</span>
</span></span><span class="line"><span class="cl">    <span class="na">user_friendly_names yes</span>
</span></span><span class="line"><span class="cl"><span class="na">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="na">blacklist {</span>
</span></span><span class="line"><span class="cl">    <span class="na">wwid &#34;.*&#34;</span>
</span></span><span class="line"><span class="cl"><span class="na">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="na">blacklist_exceptions {</span>
</span></span><span class="line"><span class="cl">    <span class="na">wwid &#34;3600140547f55689de4b49c098d9b1a3c&#34;</span>
</span></span><span class="line"><span class="cl"><span class="na">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="na">multipaths {</span>
</span></span><span class="line"><span class="cl">    <span class="na">multipath {</span>
</span></span><span class="line"><span class="cl">        <span class="na">wwid &#34;3600140547f55689de4b49c098d9b1a3c&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="na">alias mpatha</span>
</span></span><span class="line"><span class="cl">        <span class="na">path_grouping_policy &#34;multibus&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="na">path_selector &#34;round-robin 0&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="na">failback immediate</span>
</span></span><span class="line"><span class="cl">        <span class="na">rr_weight priorities</span>
</span></span><span class="line"><span class="cl">        <span class="na">no_path_retry 5</span>
</span></span><span class="line"><span class="cl">    <span class="na">}</span>
</span></span><span class="line"><span class="cl"><span class="na">}</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></td>
					<td>Ignore every device by default.</td>
			</tr>
			<tr>
					<td><code>blacklist_exceptions</code></td>
					<td>&hellip;except the iSCSI LUN with this WWID.</td>
			</tr>
			<tr>
					<td><code>alias mpatha</code></td>
					<td>Fixed name: <code>/dev/mapper/mpatha</code>.</td>
			</tr>
			<tr>
					<td><code>path_grouping_policy &quot;multibus&quot;</code></td>
					<td>All paths in one group; 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>Do not blacklist <code>devnode &quot;^sd[a-z]&quot;</code> here:</p>
<ul>
<li>iSCSI LUNs show up as <code>sdX</code> devices too, so that rule blacklists both paths and multipathd removes the <code>mpatha</code> map.</li>
<li>Blacklisting every WWID with an exception for the LUNs you want multipathed leaves your local disks alone without hiding the iSCSI paths.</li>
</ul>
<h3 id="find-the-wwid">Find the WWID <a class="anchor" data-pagefind-ignore href="#find-the-wwid" aria-label="Link to this section">#</a></h3>
<p>The config needs the <strong>WWID</strong> of your LUN. Get it before you edit the file; the default Ubuntu configuration already builds the map once both sessions are logged in:</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>Or query one of the path devices directly:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo /lib/udev/scsi_id -g -u -d /dev/sdb
</span></span></code></pre></div><h3 id="restart-the-multipath-service">Restart the multipath service <a class="anchor" data-pagefind-ignore href="#restart-the-multipath-service" aria-label="Link to this section">#</a></h3>
<p>Restart <code>multipathd</code> so it reads the new configuration:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo systemctl restart multipathd
</span></span></code></pre></div><p>Enable it at boot:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo systemctl <span class="nb">enable</span> multipathd
</span></span></code></pre></div><h2 id="verifying-the-multipathing-setup">Verifying the multipathing setup <a class="anchor" data-pagefind-ignore href="#verifying-the-multipathing-setup" aria-label="Link to this section">#</a></h2>
<h3 id="check-multipath-devices">Check multipath devices <a class="anchor" data-pagefind-ignore href="#check-multipath-devices" aria-label="Link to this section">#</a></h3>
<p>The map should show the alias, the WWID and both paths:</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>With <code>path_grouping_policy &quot;multibus&quot;</code> both paths sit in a single, active path group, so I/O is spread across them. Both <code>sdb</code> and <code>sdc</code> should be <code>active ready running</code>.</p>
<h3 id="monitor-multipathing">Monitor multipathing <a class="anchor" data-pagefind-ignore href="#monitor-multipathing" aria-label="Link to this section">#</a></h3>
<p>The daemon status and its log show path failures and recoveries:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo systemctl status multipathd
</span></span><span class="line"><span class="cl">sudo journalctl -u multipathd --no-pager --lines<span class="o">=</span><span class="m">50</span>
</span></span></code></pre></div><h2 id="simulating-a-path-failure">Simulating a path failure <a class="anchor" data-pagefind-ignore href="#simulating-a-path-failure" aria-label="Link to this section">#</a></h2>
<p>Test the failover before you rely on it. Disable one of the network interfaces:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo ip link <span class="nb">set</span> eth1 down
</span></span></code></pre></div><p>Check multipath status:</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 failed path should be marked failed, but the system should remain operational using the second path:</p>
<pre tabindex="0"><code>`-+- 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 failed faulty running
</code></pre><ul>
<li>Expect writes to pause for roughly 15 seconds while the iSCSI layer notices the dead connection.</li>
<li>After that, I/O continues on the remaining path without errors.</li>
</ul>
<p>Restore the path:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo ip link <span class="nb">set</span> eth1 up
</span></span></code></pre></div><p>Run <code>multipath -ll</code> again: the path returns to <code>active ready running</code>.</p>
<h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Cause / fix</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>mpatha</code> disappears after editing the config</td>
					<td>A <code>devnode &quot;^sd[a-z]&quot;</code> blacklist hides the iSCSI paths. Use the WWID blacklist.</td>
			</tr>
			<tr>
					<td><code>multipath -ll</code> shows nothing</td>
					<td>The WWID in the config does not match the LUN. Check it with <code>scsi_id</code>.</td>
			</tr>
			<tr>
					<td>Only one path in the map</td>
					<td>One login failed. Check <code>iscsiadm -m session</code> and the network to that portal.</td>
			</tr>
			<tr>
					<td>No sessions after a reboot</td>
					<td><code>node.startup</code> is not <code>automatic</code> for that portal.</td>
			</tr>
	</tbody>
</table>
<h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub: <a href="https://github.com/pderuiter/blog-iscsi-multipath-manual" rel="noopener">pderuiter/blog-iscsi-multipath-manual</a>. It creates an iSCSI target with two portals and an initiator on Proxmox and runs the steps from this post as Ansible roles, including the WWID-based <code>multipath.conf</code>; run <code>terraform apply</code> and then <code>ansible-playbook site.yml</code>.</p>
<h2 id="summary">Summary <a class="anchor" data-pagefind-ignore href="#summary" aria-label="Link to this section">#</a></h2>
<p>In this guide we:</p>
<ul>
<li>Logged in to the target over two paths</li>
<li>Enabled automatic iSCSI login at boot</li>
<li>Combined the paths into one multipath device with failover and load balancing</li>
<li>Verified redundancy by simulating a path failure</li>
</ul>
<p>Put your filesystem or LVM on <code>/dev/mapper/mpatha</code>, never on <code>sdb</code> or <code>sdc</code> directly.</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></channel></rss>