<?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>Storage | A DevOps Blog</title><link>https://blog.bsdserver.nl/tag/storage/</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/storage/rss/" rel="self" type="application/rss+xml"/><ttl>60</ttl><item><title>Mastering Physical Volumes and Volume groups</title><link>https://blog.bsdserver.nl/mastering-physical-volumes-and-volume-groups/</link><guid isPermaLink="false">6a5fb25718bfa60001dd6cbc</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Tue, 21 Jul 2026 17:56:44 +0000</pubDate><description>Running out of space on your Linux VM?</description><category>Linux</category><category>LVM</category><category>Storage</category><category>Sysadmin</category><media:content url="https://blog.bsdserver.nl/content/images/2026/07/mastering-lvm-1.png" medium="image"/><content:encoded><![CDATA[<p>Running out of space on your Linux VM? LVM (Logical Volume Manager) and VMware vSphere make disk resizing straightforward, even when an entire unpartitioned disk is part of a volume group.</p>
<p>This post covers the everyday physical volume (PV) and volume group (VG) tasks: growing a disk, adding one, migrating data to a new disk, backing up VG metadata, and moving, cloning, splitting and checking volume groups. Each scenario says when you need it, then shows the commands.</p>
<h2 id="which-scenario-do-you-need">Which scenario do you need? <a class="anchor" data-pagefind-ignore href="#which-scenario-do-you-need" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Scenario</th>
					<th>Use it when</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><a href="#resizing-an-lvm-disk-in-vsphere">Resize a whole-disk PV</a></td>
					<td>You made a VMDK bigger and the PV sits on the raw disk.</td>
			</tr>
			<tr>
					<td><a href="#scenario-expanding-a-partition-backed-pv-with-parted">Resize a partition-backed PV</a></td>
					<td>You made a VMDK bigger and the PV sits on a partition (<code>sdb1</code>).</td>
			</tr>
			<tr>
					<td><a href="#scenario-adding-a-larger-pv-and-migrating-data">Add a larger PV and migrate data</a></td>
					<td>You want to replace old disks with one new disk, online.</td>
			</tr>
			<tr>
					<td><a href="#scenario-backing-up-and-restoring-volume-group-configuration">Back up and restore VG metadata</a></td>
					<td>Before risky changes, or to undo an accidental one.</td>
			</tr>
			<tr>
					<td><a href="#scenario-moving-lvm-pvs-from-one-machine-to-another">Move PVs to another machine</a></td>
					<td>LUNs or disks move to a different server.</td>
			</tr>
			<tr>
					<td><a href="#scenario-using-vgimportclone-for-cloned-volume-groups">vgimportclone</a></td>
					<td>A cloned disk has the same VG name and UUIDs as the original.</td>
			</tr>
			<tr>
					<td><a href="#scenario-using-vgimportdevices-for-importing-volume-groups-from-specific-devices">vgimportdevices</a></td>
					<td>The system uses the LVM devices file and must use a VG&rsquo;s disks.</td>
			</tr>
			<tr>
					<td><a href="#scenario-splitting-a-volume-group-with-vgsplit">vgsplit</a></td>
					<td>Some LVs should become their own VG.</td>
			</tr>
			<tr>
					<td><a href="#scenario-checking-volume-group-metadata-with-vgck">vgck</a></td>
					<td>You suspect damaged VG metadata.</td>
			</tr>
	</tbody>
</table>
<h2 id="whole-disk-or-partition-as-pv">Whole disk or partition as PV? <a class="anchor" data-pagefind-ignore href="#whole-disk-or-partition-as-pv" aria-label="Link to this section">#</a></h2>
<p>You can add either a partition or an entire disk to a VG. Adding the unpartitioned disk skips the partitioning step entirely, which makes growing it simpler.</p>
<table>
	<thead>
			<tr>
					<th></th>
					<th>Whole disk (<code>/dev/sdb</code>)</th>
					<th>Partition (<code>/dev/sdb1</code>)</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Growing</td>
					<td>Rescan + <code>pvresize</code></td>
					<td>Rescan + grow partition + <code>pvresize</code></td>
			</tr>
			<tr>
					<td>Space use</td>
					<td>Whole disk, no partition boundaries</td>
					<td>Up to the partition end</td>
			</tr>
			<tr>
					<td>Portability</td>
					<td>Other systems and tools may not recognise a disk without a partition table</td>
					<td>Recognised everywhere</td>
			</tr>
			<tr>
					<td>Backup/recovery tools</td>
					<td>May expect a partition table</td>
					<td>Work as expected</td>
			</tr>
			<tr>
					<td>OS disk</td>
					<td>Not usable, data disks only</td>
					<td>Usable</td>
			</tr>
	</tbody>
</table>
<h3 id="when-to-use-which">When to use which <a class="anchor" data-pagefind-ignore href="#when-to-use-which" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Whole disk</strong>: data disks used only by LVM on servers. Fewest steps.</li>
<li><strong>Partition</strong>: OS disks, or disks shared between purposes or environments.</li>
</ul>
<h2 id="resizing-an-lvm-disk-in-vsphere">Resizing an LVM disk in vSphere <a class="anchor" data-pagefind-ignore href="#resizing-an-lvm-disk-in-vsphere" aria-label="Link to this section">#</a></h2>
<p>The PV sits on the whole disk. After growing the VMDK, Linux and LVM each need to be told about the new size.</p>
<p>The flow: grow VMDK → rescan → <code>pvresize</code> → VG has free space → <code>lvresize -r</code> or <code>lvcreate</code>.</p>
<h3 id="step-1-resize-the-disk-in-vsphere">Step 1: Resize the disk in vSphere <a class="anchor" data-pagefind-ignore href="#step-1-resize-the-disk-in-vsphere" aria-label="Link to this section">#</a></h3>
<p>Increase the size of the disk in the VMware interface:</p>
<ol>
<li>Log in to the vSphere client or vCenter.</li>
<li>Locate the VM you want to resize.</li>
<li>Edit the VM settings and increase the size of the existing virtual disk (e.g., from 100GB to 200GB).</li>
<li>Save your changes.</li>
</ol>
<p>The VM now has a larger disk, but the operating system still needs to recognise and use the new space.</p>
<h3 id="step-2-rescan-the-disk-in-the-vm">Step 2: Rescan the disk in the VM <a class="anchor" data-pagefind-ignore href="#step-2-rescan-the-disk-in-the-vm" aria-label="Link to this section">#</a></h3>
<p>A SCSI rescan makes the kernel re-read the disk size, without a reboot:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nb">echo</span> <span class="m">1</span> &gt; /sys/class/scsi_device/0:0:0:0/device/rescan
</span></span></code></pre></div><p>Replace <code>0:0:0:0</code> with the identifier (host:channel:target:LUN) of your disk. List them with:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">ls /sys/class/scsi_device/
</span></span></code></pre></div><h3 id="step-3-verify-the-disk-size">Step 3: Verify the disk size <a class="anchor" data-pagefind-ignore href="#step-3-verify-the-disk-size" aria-label="Link to this section">#</a></h3>
<p>Check that the VM recognises the new size:</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>The output should show the increased capacity for your disk (e.g., <code>/dev/sdb</code>).</p>
<h3 id="step-4-extend-the-physical-volume-pv">Step 4: Extend the physical volume (PV) <a class="anchor" data-pagefind-ignore href="#step-4-extend-the-physical-volume-pv" aria-label="Link to this section">#</a></h3>
<p><code>pvresize</code> grows the PV to the new disk size, so the VG gets the extra space:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">pvresize /dev/sdb
</span></span></code></pre></div><h3 id="step-5-alternative-add-a-brand-new-disk-to-the-volume-group">Step 5: (Alternative) Add a brand-new disk to the volume group <a class="anchor" data-pagefind-ignore href="#step-5-alternative-add-a-brand-new-disk-to-the-volume-group" aria-label="Link to this section">#</a></h3>
<p>If you added a completely new disk instead of growing one, <code>pvresize</code> does not apply. Initialise the new disk as a PV, then add it to the existing VG:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">pvcreate /dev/sdb
</span></span><span class="line"><span class="cl">vgextend &lt;vg_name&gt; /dev/sdb
</span></span></code></pre></div><h3 id="step-6-verify-the-volume-group-vg-size">Step 6: Verify the volume group (VG) size <a class="anchor" data-pagefind-ignore href="#step-6-verify-the-volume-group-vg-size" aria-label="Link to this section">#</a></h3>
<p>Check that the extra space is available in the VG:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">vgdisplay
</span></span></code></pre></div><p>The &ldquo;Free PE / Size&rdquo; field shows the capacity available for allocation.</p>
<h3 id="step-7-expand-your-logical-volume-lv">Step 7: Expand your logical volume (LV) <a class="anchor" data-pagefind-ignore href="#step-7-expand-your-logical-volume-lv" aria-label="Link to this section">#</a></h3>
<p>Use the new space for a new LV, or grow an existing one.</p>
<table>
	<thead>
			<tr>
					<th>Option</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>lvcreate</code> + <code>mkfs</code></td>
					<td>A new filesystem, e.g. a separate mount for data.</td>
			</tr>
			<tr>
					<td><code>lvresize -r</code></td>
					<td>Growing an existing LV and its filesystem in one step.</td>
			</tr>
	</tbody>
</table>
<p><strong>Create a new LV</strong>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">lvcreate -L 100G -n new_lv my_volume_group
</span></span><span class="line"><span class="cl">mkfs.ext4 /dev/my_volume_group/new_lv  <span class="c1"># Formatting with a filesystem</span>
</span></span></code></pre></div><p><strong>Extend an existing LV</strong> (<code>-r</code> resizes the filesystem as well):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">lvresize -r -L +100G /dev/my_volume_group/my_logical_volume  <span class="c1"># The -r switch automatically resizes the filesystem</span>
</span></span></code></pre></div><h2 id="scenario-expanding-a-partition-backed-pv-with-parted">Scenario: Expanding a partition-backed PV with parted <a class="anchor" data-pagefind-ignore href="#scenario-expanding-a-partition-backed-pv-with-parted" aria-label="Link to this section">#</a></h2>
<p>When the PV sits on a partition such as <code>/dev/sdb1</code>, growing the disk is not enough. LVM can only use the space that the partition exposes, so the partition must grow first.</p>
<ul>
<li>Modern kernels support growing a partition while it is in use, so this also works online without a reboot.</li>
<li>The flow: rescan → <code>parted resizepart</code> → <code>partprobe</code> (if needed) → <code>pvresize /dev/sdb1</code>.</li>
</ul>
<h3 id="step-1-rescan-and-verify-the-new-disk-size">Step 1: Rescan and verify the new disk size <a class="anchor" data-pagefind-ignore href="#step-1-rescan-and-verify-the-new-disk-size" aria-label="Link to this section">#</a></h3>
<p>Rescan the disk exactly as in steps 2 and 3 above. <code>lsblk</code> then shows the mismatch to fix:</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><span class="line"><span class="cl">NAME   MAJ:MIN RM  SIZE RO TYPE MOUNTPOINT
</span></span><span class="line"><span class="cl">sdb      8:16   <span class="m">0</span>  200G  <span class="m">0</span> disk
</span></span><span class="line"><span class="cl">└─sdb1   8:17   <span class="m">0</span>  100G  <span class="m">0</span> part
</span></span></code></pre></div><p>The disk (<code>sdb</code>) is 200GB, but the partition (<code>sdb1</code>) is still 100GB.</p>
<h3 id="step-2-grow-the-partition-with-parted">Step 2: Grow the partition with parted <a class="anchor" data-pagefind-ignore href="#step-2-grow-the-partition-with-parted" aria-label="Link to this section">#</a></h3>
<p>Start <code>parted</code> on the disk (not the partition):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">parted /dev/sdb
</span></span><span class="line"><span class="cl"><span class="o">(</span>parted<span class="o">)</span> print
</span></span></code></pre></div><p>If the disk uses GPT, <code>parted</code> may warn that not all of the disk space is in use and offer to fix it. Answer <code>Fix</code>: this moves the backup GPT header to the new end of the disk, which is required before you can extend the partition.</p>
<p>Now resize the partition. <code>resizepart</code> takes the partition number and the new end; <code>100%</code> means &ldquo;up to the end of the disk&rdquo;:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="o">(</span>parted<span class="o">)</span> resizepart <span class="m">1</span> 100%
</span></span><span class="line"><span class="cl"><span class="o">(</span>parted<span class="o">)</span> quit
</span></span></code></pre></div><ul>
<li>Older <code>parted</code> releases ask for confirmation when the partition is in use; answer <code>Yes</code>. Current versions (parted 3.6 on Ubuntu 24.04) grow an in-use partition without asking.</li>
<li>Growing is safe while online: the start of the partition does not move, so the data on it is untouched.</li>
</ul>
<blockquote>
<p><strong>Tip:</strong> If you have <code>cloud-utils</code> installed, <code>growpart /dev/sdb 1</code> does the same thing in a single non-interactive command, which is handy for automation with Ansible or cloud-init.</p>
</blockquote>
<h3 id="step-3-let-the-kernel-re-read-the-partition-table">Step 3: Let the kernel re-read the partition table <a class="anchor" data-pagefind-ignore href="#step-3-let-the-kernel-re-read-the-partition-table" aria-label="Link to this section">#</a></h3>
<p><code>parted</code> usually informs the kernel automatically. If <code>lsblk</code> still shows the old size, force a re-read:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">partprobe /dev/sdb
</span></span></code></pre></div><p><code>lsblk</code> should now show <code>sdb1</code> at the full 200GB.</p>
<h3 id="step-4-resize-the-physical-volume">Step 4: Resize the physical volume <a class="anchor" data-pagefind-ignore href="#step-4-resize-the-physical-volume" aria-label="Link to this section">#</a></h3>
<p>Tell LVM to claim the new space in the partition:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">pvresize /dev/sdb1
</span></span></code></pre></div><p>Verify with <code>pvs</code> or <code>vgdisplay</code>: the &ldquo;Free PE / Size&rdquo; of the VG should have grown. Extend your LV as in Step 7 above with <code>lvresize -r</code>.</p>
<h2 id="scenario-adding-a-larger-pv-and-migrating-data">Scenario: Adding a larger PV and migrating data <a class="anchor" data-pagefind-ignore href="#scenario-adding-a-larger-pv-and-migrating-data" aria-label="Link to this section">#</a></h2>
<p><code>pvmove</code> moves the data from old PVs to a new one while the LVs stay in use. Use it to replace several small disks with one large disk, or to retire old disks.</p>
<p>The setup:</p>
<ul>
<li>Two existing PVs (PV1 and PV2), e.g. 100GB each.</li>
<li>A new PV (PV3), larger than PV1 and PV2 together, e.g. 250GB.</li>
<li>Goal: move all data to PV3, then remove PV1 and PV2 from the VG.</li>
</ul>
<p>The flow: <code>pvcreate</code> → <code>vgextend</code> → <code>pvmove</code> (per old PV) → <code>vgreduce</code> → <code>pvremove</code>.</p>
<h3 id="step-1-add-the-new-physical-volume">Step 1: Add the new physical volume <a class="anchor" data-pagefind-ignore href="#step-1-add-the-new-physical-volume" aria-label="Link to this section">#</a></h3>
<p>Add the new disk in vSphere and make it available to your VM. Initialise it as a PV:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">pvcreate /dev/sdc  <span class="c1"># Assuming the new disk is /dev/sdc</span>
</span></span></code></pre></div><p>Add it to the volume group:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">vgextend my_volume_group /dev/sdc
</span></span></code></pre></div><h3 id="step-2-migrate-data-to-the-new-physical-volume">Step 2: Migrate data to the new physical volume <a class="anchor" data-pagefind-ignore href="#step-2-migrate-data-to-the-new-physical-volume" aria-label="Link to this section">#</a></h3>
<p><code>pvmove</code> moves all extents from the first PV to the second. It runs online; the LVs stay mounted:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">pvmove /dev/sdb /dev/sdc
</span></span><span class="line"><span class="cl">pvmove /dev/sda /dev/sdc
</span></span></code></pre></div><p>This moves all extents from <code>/dev/sdb</code> and <code>/dev/sda</code> (the smaller PVs) to <code>/dev/sdc</code> (the new, larger PV).</p>
<h3 id="step-3-verify-the-migration">Step 3: Verify the migration <a class="anchor" data-pagefind-ignore href="#step-3-verify-the-migration" aria-label="Link to this section">#</a></h3>
<p>Check where the extents are now:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">pvs
</span></span></code></pre></div><p><code>/dev/sdc</code> should now hold all the extents; <code>/dev/sda</code> and <code>/dev/sdb</code> should be empty (PFree equals PSize).</p>
<h3 id="step-4-remove-the-old-physical-volumes">Step 4: Remove the old physical volumes <a class="anchor" data-pagefind-ignore href="#step-4-remove-the-old-physical-volumes" aria-label="Link to this section">#</a></h3>
<p><code>vgreduce</code> removes the empty PVs from the volume group:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">vgreduce my_volume_group /dev/sda
</span></span><span class="line"><span class="cl">vgreduce my_volume_group /dev/sdb
</span></span></code></pre></div><p><code>pvremove</code> then wipes the LVM label, if you no longer need the disks:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">pvremove /dev/sda
</span></span><span class="line"><span class="cl">pvremove /dev/sdb
</span></span></code></pre></div><h2 id="scenario-backing-up-and-restoring-volume-group-configuration">Scenario: Backing up and restoring volume group configuration <a class="anchor" data-pagefind-ignore href="#scenario-backing-up-and-restoring-volume-group-configuration" aria-label="Link to this section">#</a></h2>
<p>VG metadata describes which extents belong to which LV. Back it up before significant changes, such as moving PVs between machines or migrations.</p>
<table>
	<thead>
			<tr>
					<th>Command</th>
					<th>What it does</th>
					<th>When</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>vgcfgrestore</code></td>
					<td>Writes saved metadata back to the PVs</td>
					<td>Metadata damaged, or an unintended change (e.g. <code>lvremove</code>)</td>
			</tr>
			<tr>
					<td><code>vgcfgbackup</code></td>
					<td>Saves the current metadata to a file</td>
					<td>Before major changes</td>
			</tr>
	</tbody>
</table>
<h3 id="restoring-with-vgcfgrestore">Restoring with vgcfgrestore <a class="anchor" data-pagefind-ignore href="#restoring-with-vgcfgrestore" aria-label="Link to this section">#</a></h3>
<p>Deactivate the LVs first, then restore the VG&rsquo;s metadata from its backup file. With active LVs, <code>vgcfgrestore</code> refuses to continue unless you confirm:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">vgchange -an my_volume_group
</span></span><span class="line"><span class="cl">vgcfgrestore my_volume_group
</span></span></code></pre></div><p>LVM rewrites <code>/etc/lvm/backup/my_volume_group</code> automatically after every metadata change. After an unintended change, that file already contains the new state. Earlier versions are kept in <code>/etc/lvm/archive/</code>: list them and restore the one taken <em>before</em> the change:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">vgcfgrestore --list my_volume_group
</span></span><span class="line"><span class="cl">vgcfgrestore -f /etc/lvm/archive/my_volume_group_00011-1234567890.vg my_volume_group
</span></span></code></pre></div><h3 id="backing-up-with-vgcfgbackup">Backing up with vgcfgbackup <a class="anchor" data-pagefind-ignore href="#backing-up-with-vgcfgbackup" aria-label="Link to this section">#</a></h3>
<p><code>vgcfgbackup</code> saves the VG&rsquo;s metadata: its structure and the LVs in it. Run it before resizing, migration or removing PVs:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">vgcfgbackup my_volume_group
</span></span></code></pre></div><p>By default, this creates a backup file in <code>/etc/lvm/backup/</code>. You can also specify a custom path.</p>
<h3 id="best-practices">Best practices <a class="anchor" data-pagefind-ignore href="#best-practices" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Back up before major changes</strong>: run <code>vgcfgbackup</code> before <code>pvmove</code>, <code>vgreduce</code> or even adding new PVs.</li>
<li><strong>Store backups off the machine</strong>: a backup on the failed disk does not help.</li>
<li><strong>Test restores</strong>: practise <code>vgcfgrestore</code> in a test environment before you need it in production.</li>
</ul>
<h2 id="scenario-moving-lvm-pvs-from-one-machine-to-another">Scenario: Moving LVM PVs from one machine to another <a class="anchor" data-pagefind-ignore href="#scenario-moving-lvm-pvs-from-one-machine-to-another" aria-label="Link to this section">#</a></h2>
<p>A VG can move to another server with its disks, for example two PVs on iSCSI LUNs. You export the VG on the old server and import it on the new one.</p>
<p>The flow: <code>umount</code> → <code>vgchange -an</code> → <code>vgexport</code> → move LUNs → <code>vgimport</code> → <code>vgchange -ay</code> → <code>mount</code>.</p>
<h3 id="step-1-unmount-the-logical-volumes">Step 1: Unmount the logical volumes <a class="anchor" data-pagefind-ignore href="#step-1-unmount-the-logical-volumes" aria-label="Link to this section">#</a></h3>
<p>Unmount every filesystem on the VG&rsquo;s logical volumes:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">umount /mnt/my_logical_volume
</span></span></code></pre></div><p>Repeat this for each mounted LV.</p>
<h3 id="step-2-deactivate-the-volume-group">Step 2: Deactivate the volume group <a class="anchor" data-pagefind-ignore href="#step-2-deactivate-the-volume-group" aria-label="Link to this section">#</a></h3>
<p>Deactivating removes the LV devices, so nothing can write to them during the move:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">vgchange -an my_volume_group
</span></span></code></pre></div><h3 id="step-3-export-the-volume-group">Step 3: Export the volume group <a class="anchor" data-pagefind-ignore href="#step-3-export-the-volume-group" aria-label="Link to this section">#</a></h3>
<p><code>vgexport</code> marks the VG as exported, so the old server no longer uses it and the destination can import it:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">vgexport my_volume_group
</span></span></code></pre></div><h3 id="step-4-move-the-iscsi-luns-to-the-destination-machine">Step 4: Move the iSCSI LUNs to the destination machine <a class="anchor" data-pagefind-ignore href="#step-4-move-the-iscsi-luns-to-the-destination-machine" aria-label="Link to this section">#</a></h3>
<p>Connect the destination machine to the iSCSI LUNs that hold the PVs. This depends on your iSCSI setup, but typically means logging in to the iSCSI target from the destination. See <a href="https://blog.bsdserver.nl/automating-iscsi-initiator-configuration-with-ansible/">Automating iSCSI Initiator Configuration with Ansible</a>.</p>
<h3 id="step-5-import-the-volume-group-on-the-destination-machine">Step 5: Import the volume group on the destination machine <a class="anchor" data-pagefind-ignore href="#step-5-import-the-volume-group-on-the-destination-machine" aria-label="Link to this section">#</a></h3>
<p>Once the LUNs are connected, import the VG:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">vgimport my_volume_group
</span></span></code></pre></div><h3 id="step-6-activate-the-volume-group">Step 6: Activate the volume group <a class="anchor" data-pagefind-ignore href="#step-6-activate-the-volume-group" aria-label="Link to this section">#</a></h3>
<p>Activation makes the LV devices available:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">vgchange -ay my_volume_group
</span></span></code></pre></div><h3 id="step-7-mount-the-logical-volumes">Step 7: Mount the logical volumes <a class="anchor" data-pagefind-ignore href="#step-7-mount-the-logical-volumes" aria-label="Link to this section">#</a></h3>
<p>Mount the LVs on their mount points:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">mount /dev/my_volume_group/my_logical_volume /mnt/my_logical_volume
</span></span></code></pre></div><p>Repeat this for each LV. Add them to <code>/etc/fstab</code> on the new server if they must mount at boot.</p>
<h2 id="scenario-using-vgimportclone-for-cloned-volume-groups">Scenario: Using vgimportclone for cloned volume groups <a class="anchor" data-pagefind-ignore href="#scenario-using-vgimportclone-for-cloned-volume-groups" aria-label="Link to this section">#</a></h2>
<p>A cloned disk (a storage snapshot or a copied VMDK) has the same VG name and UUIDs as the original. When both are visible on one system, LVM cannot tell them apart. <code>vgimportclone</code> gives the clone new UUIDs and a new name.</p>
<h3 id="step-1-attach-the-cloned-disk">Step 1: Attach the cloned disk <a class="anchor" data-pagefind-ignore href="#step-1-attach-the-cloned-disk" aria-label="Link to this section">#</a></h3>
<p>Attach the cloned disk to the destination machine and check that the operating system recognises it.</p>
<h3 id="step-2-use-vgimportclone">Step 2: Use vgimportclone <a class="anchor" data-pagefind-ignore href="#step-2-use-vgimportclone" aria-label="Link to this section">#</a></h3>
<p>Import the cloned VG under a new name:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">vgimportclone -n new_volume_group_name /dev/sdX
</span></span></code></pre></div><p>Replace <code>/dev/sdX</code> with the cloned disk and <code>new_volume_group_name</code> with the new VG name.</p>
<h2 id="scenario-using-vgimportdevices-for-importing-volume-groups-from-specific-devices">Scenario: Using vgimportdevices for importing volume groups from specific devices <a class="anchor" data-pagefind-ignore href="#scenario-using-vgimportdevices-for-importing-volume-groups-from-specific-devices" aria-label="Link to this section">#</a></h2>
<p>On systems that use the LVM devices file (<code>/etc/lvm/devices/system.devices</code>, enabled by default on RHEL 9), LVM ignores every device that is not listed in it. <code>vgimportdevices</code> adds the devices of a volume group to that file.</p>
<p>Use it when:</p>
<ul>
<li>A system has multiple disks with different VGs.</li>
<li>LVM should only use the devices of the VGs you choose, to avoid conflicts with other setups.</li>
</ul>
<h3 id="step-1-list-available-devices">Step 1: List available devices <a class="anchor" data-pagefind-ignore href="#step-1-list-available-devices" aria-label="Link to this section">#</a></h3>
<p>See which PVs exist and which VG each belongs to:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">pvs
</span></span></code></pre></div><h3 id="step-2-import-the-volume-groups-devices">Step 2: Import the volume group&rsquo;s devices <a class="anchor" data-pagefind-ignore href="#step-2-import-the-volume-groups-devices" aria-label="Link to this section">#</a></h3>
<p><code>vgimportdevices</code> takes VG names, not device names, and adds all PVs of that VG to the devices file:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">vgimportdevices my_volume_group
</span></span><span class="line"><span class="cl">lvmdevices
</span></span></code></pre></div><ul>
<li><code>lvmdevices</code> shows the resulting list.</li>
<li>Passing device paths (<code>vgimportdevices my_volume_group /dev/sdX</code>) fails with <code>Volume group &quot;sdX&quot; not found</code>.</li>
<li>On Debian and Ubuntu the command is only available as <code>lvm vgimportdevices</code>, and the devices file is disabled there by default (<code>use_devicesfile = 0</code>).</li>
</ul>
<h2 id="scenario-splitting-a-volume-group-with-vgsplit">Scenario: Splitting a volume group with vgsplit <a class="anchor" data-pagefind-ignore href="#scenario-splitting-a-volume-group-with-vgsplit" aria-label="Link to this section">#</a></h2>
<p><code>vgsplit</code> moves part of a VG into a new VG. Use it to prepare some LVs for a move to another machine, or when reorganising storage.</p>
<ul>
<li><code>vgsplit</code> moves whole PVs, so the LVs you split off must live on PVs of their own.</li>
<li>The LVs that move must be inactive.</li>
</ul>
<h3 id="step-1-verify-volume-group-and-logical-volumes">Step 1: Verify volume group and logical volumes <a class="anchor" data-pagefind-ignore href="#step-1-verify-volume-group-and-logical-volumes" aria-label="Link to this section">#</a></h3>
<p>Check the structure of the VG and list all LVs:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">vgdisplay my_volume_group
</span></span><span class="line"><span class="cl">lvdisplay
</span></span></code></pre></div><h3 id="step-2-split-the-volume-group">Step 2: Split the volume group <a class="anchor" data-pagefind-ignore href="#step-2-split-the-volume-group" aria-label="Link to this section">#</a></h3>
<p>Deactivate the LVs you want to move, then create a new VG from the PV(s) that hold them:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">lvchange -an my_volume_group/lv_name1 my_volume_group/lv_name2
</span></span><span class="line"><span class="cl">vgsplit my_volume_group new_volume_group /dev/sdX
</span></span></code></pre></div><p>Alternatively, name one LV and let <code>vgsplit</code> move the PVs it lives on. Any other LV on those PVs moves along with it:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">vgsplit -n lv_name1 my_volume_group new_volume_group
</span></span></code></pre></div><ul>
<li>Replace <code>new_volume_group</code> with the new VG name, <code>/dev/sdX</code> with the PV that holds the LVs, and <code>lv_name1</code>, <code>lv_name2</code> with the LVs you want to move.</li>
<li>Listing LV names as plain arguments does not work: <code>vgsplit</code> treats them as PV names and fails with <code>Physical volume lv_name1 not in volume group my_volume_group</code>.</li>
</ul>
<h3 id="step-3-verify-the-split">Step 3: Verify the split <a class="anchor" data-pagefind-ignore href="#step-3-verify-the-split" aria-label="Link to this section">#</a></h3>
<p>Check that both VGs exist and contain the expected LVs:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">vgdisplay
</span></span></code></pre></div><h2 id="scenario-checking-volume-group-metadata-with-vgck">Scenario: Checking volume group metadata with vgck <a class="anchor" data-pagefind-ignore href="#scenario-checking-volume-group-metadata-with-vgck" aria-label="Link to this section">#</a></h2>
<p><code>vgck</code> checks the consistency of the VG metadata. Use it when you suspect corruption, for example after a crash.</p>
<h3 id="step-1-run-vgck-on-the-volume-group">Step 1: Run vgck on the volume group <a class="anchor" data-pagefind-ignore href="#step-1-run-vgck-on-the-volume-group" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">vgck my_volume_group
</span></span></code></pre></div><p>Replace <code>my_volume_group</code> with the name of the VG to check.</p>
<h3 id="step-2-review-the-output">Step 2: Review the output <a class="anchor" data-pagefind-ignore href="#step-2-review-the-output" aria-label="Link to this section">#</a></h3>
<p><code>vgck</code> reports any inconsistencies it finds. If it finds problems, you may need <code>vgcfgrestore</code> (see above) or manual repair.</p>
<h3 id="when-to-use-vgck">When to use vgck <a class="anchor" data-pagefind-ignore href="#when-to-use-vgck" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>After a system crash</strong> or abrupt shutdown: check that the VG metadata is not corrupted.</li>
<li><strong>Before major operations</strong> like <code>pvmove</code> or <code>vgreduce</code>: make sure the VG is healthy first.</li>
</ul>
<h2 id="best-practices-for-disk-resizing-and-migration-in-vsphere">Best practices for disk resizing and migration in vSphere <a class="anchor" data-pagefind-ignore href="#best-practices-for-disk-resizing-and-migration-in-vsphere" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Backup before operations</strong>: always have a recent backup before resizing or migrating data.</li>
<li><strong>Monitor performance</strong>: <code>pvmove</code> is I/O-intensive. Watch disk I/O and system performance, especially in production.</li>
<li><strong>Plan for slowdown</strong>: <code>pvmove</code> runs online, but expect reduced performance during the migration.</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-lvm-pv-vg" rel="noopener">pderuiter/blog-lvm-pv-vg</a>. It creates a VM with three spare disks on Proxmox and automates the resize (rescan, growpart, pvresize), add-a-disk and pvmove migration scenarios, followed by <code>lvresize -r</code>; run <code>terraform apply</code> and then <code>ansible-playbook site.yml</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Whole-disk PVs</strong> are the simplest to grow: rescan and <code>pvresize</code>. Partitions add a <code>parted</code> or <code>growpart</code> step but are more portable.</li>
<li><strong><code>pvmove</code></strong> replaces disks online.</li>
<li><strong><code>vgexport</code> / <code>vgimport</code></strong> move a VG with its LUNs to another server; <code>vgimportclone</code> handles clones.</li>
<li><strong><code>vgcfgbackup</code>, <code>vgcfgrestore</code> and <code>vgck</code></strong> protect and check the metadata.</li>
</ul>
<p>For the basic add-a-disk procedure, see <a href="https://blog.bsdserver.nl/expanding-disk-space-on-lvm-a-step-by-step-guide/">Expanding Disk Space on LVM: A Step-by-Step Guide</a>.</p>
]]></content:encoded></item><item><title>Automating iSCSI Multipathing with Ansible</title><link>https://blog.bsdserver.nl/automating-iscsi-multipathing-with-ansible/</link><guid isPermaLink="false">693b680679eb54000160a52b</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 00:55:34 +0000</pubDate><description>Multipathing (MPIO - Multipath I/O) is essential for high availability and performance in iSCSI storage environments.</description><category>Linux</category><category>Storage</category><category>iSCSI</category><category>Ansible</category><category>High availability</category><category>Automation</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/ansible-iscsi-multipathing.png" medium="image"/><content:encoded><![CDATA[<p>A single iSCSI connection is a single point of failure. One broken switch port or NIC, and the server loses its disk.</p>
<p>Multipathing (MPIO, Multipath I/O) connects the initiator to the target over two or more network paths and shows them as one disk. This post builds an Ansible role that installs the iSCSI and multipath tools, logs in over every path and combines them into one multipath device.</p>
<h2 id="why-use-multipathing">Why use multipathing? <a class="anchor" data-pagefind-ignore href="#why-use-multipathing" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Redundancy</strong>: if one network path fails, another takes over</li>
<li><strong>Load balancing</strong>: I/O is spread across all paths</li>
<li><strong>Higher bandwidth</strong>: more network interfaces, more throughput</li>
<li><strong>Automatic failover</strong>: no manual action when a path fails</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> when the target has portals on two or more storage networks and the server needs its disk to survive a network failure.</li>
<li><strong>Skip it</strong> when there is only one network path. Multipath adds nothing then; the plain initiator setup from <a href="https://blog.bsdserver.nl/automating-iscsi-initiator-configuration-with-ansible/">Automating iSCSI Initiator Configuration with Ansible</a> is enough.</li>
</ul>
<p>Want to understand each step by hand first? See <a href="https://blog.bsdserver.nl/setting-up-iscsi-multipathing-manually-on-linux-2/">Setting Up iSCSI Multipathing Manually on Linux</a>.</p>
<h2 id="how-it-works">How it works <a class="anchor" data-pagefind-ignore href="#how-it-works" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Ansible role <code>iscsi_multipath</code></td>
					<td>Control machine</td>
					<td>Installs packages, renders configs, logs in to every portal.</td>
			</tr>
			<tr>
					<td><code>iscsid</code></td>
					<td>Initiator</td>
					<td>One iSCSI session per portal (path).</td>
			</tr>
			<tr>
					<td><code>multipathd</code></td>
					<td>Initiator</td>
					<td>Sees the same LUN on every path (same WWID) and combines the paths into one <code>mpatha</code> device.</td>
			</tr>
			<tr>
					<td>iSCSI target</td>
					<td>Storage server</td>
					<td>One portal per storage network, same LUN behind both.</td>
			</tr>
	</tbody>
</table>
<p>The flow: log in to portal 1 → <code>sdb</code> appears → log in to portal 2 → <code>sdc</code> appears → <code>multipathd</code> sees the same WWID on both → creates <code>/dev/mapper/mpatha</code> → you use only <code>mpatha</code>.</p>
<h2 id="the-role-iscsi_multipath">The role: iscsi_multipath <a class="anchor" data-pagefind-ignore href="#the-role-iscsi_multipath" aria-label="Link to this section">#</a></h2>
<p>The role:</p>
<ul>
<li>Installs the required packages</li>
<li>Configures <code>iscsid.conf</code> and <code>multipath.conf</code></li>
<li>Discovers the iSCSI targets on every portal</li>
<li>Logs in to every path</li>
<li>Keeps <code>multipathd</code> enabled and running</li>
</ul>
<h3 id="role-directory-structure">Role directory structure <a class="anchor" data-pagefind-ignore href="#role-directory-structure" aria-label="Link to this section">#</a></h3>
<p>A standard role layout; the files below fill <code>defaults</code>, <code>tasks</code>, <code>handlers</code> and <code>templates</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">iscsi_multipath/
</span></span><span class="line"><span class="cl">├── tasks/
</span></span><span class="line"><span class="cl">│   ├── main.yml
</span></span><span class="line"><span class="cl">├── handlers/
</span></span><span class="line"><span class="cl">│   ├── main.yml
</span></span><span class="line"><span class="cl">├── templates/
</span></span><span class="line"><span class="cl">│   ├── iscsid.conf.j2
</span></span><span class="line"><span class="cl">│   ├── multipath.conf.j2
</span></span><span class="line"><span class="cl">├── vars/
</span></span><span class="line"><span class="cl">│   ├── main.yml
</span></span><span class="line"><span class="cl">├── defaults/
</span></span><span class="line"><span class="cl">│   ├── main.yml
</span></span><span class="line"><span class="cl">├── meta/
</span></span><span class="line"><span class="cl">│   ├── main.yml
</span></span><span class="line"><span class="cl">├── README.md
</span></span></code></pre></div><h2 id="role-configuration">Role configuration <a class="anchor" data-pagefind-ignore href="#role-configuration" aria-label="Link to this section">#</a></h2>
<h3 id="define-variables">Define variables <a class="anchor" data-pagefind-ignore href="#define-variables" aria-label="Link to this section">#</a></h3>
<p><code>iscsi_target_ips</code> lists one portal per path; the role discovers and logs in to each. Create <code>defaults/main.yml</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">iscsi_target_ips</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="s2">&#34;192.168.2.253&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="s2">&#34;192.168.3.253&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">iscsi_target_name</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;iqn.2025-03.com.example:storage&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">iscsi_chap_username</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ vault_iscsi_chap_username }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">iscsi_chap_password</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ vault_iscsi_chap_password }}&#34;</span><span class="w">
</span></span></span></code></pre></div><p>The CHAP credentials themselves don&rsquo;t belong in the role. Keep them in an Ansible Vault encrypted file next to your playbook and inventory, <code>group_vars/all/vault.yml</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">ansible-vault create group_vars/all/vault.yml
</span></span></code></pre></div><p>Ansible asks for a new vault password and opens your editor. Add the CHAP credentials, prefixed with <code>vault_</code> so it is obvious where they come from:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">vault_iscsi_chap_username</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;your_username&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">vault_iscsi_chap_password</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;your_secure_password&#34;</span><span class="w">
</span></span></span></code></pre></div><ul>
<li>On disk the file starts with <code>$ANSIBLE_VAULT;1.1;AES256</code> and is safe to commit.</li>
<li>Already have a plaintext file? Encrypt it in place with <code>ansible-vault encrypt group_vars/all/vault.yml</code>.</li>
<li>Use <code>ansible-vault view</code> or <code>ansible-vault edit</code> to read or change it later.</li>
</ul>
<h3 id="tasks">Tasks <a class="anchor" data-pagefind-ignore href="#tasks" aria-label="Link to this section">#</a></h3>
<p>The tasks install the tools, write both configs, load the multipath config and then log in over every path. Create <code>tasks/main.yml</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nn">---</span><span class="w">
</span></span></span><span class="line"><span class="cl">- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Install iSCSI and multipath packages</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ansible.builtin.apt</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">name</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">open-iscsi</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">multipath-tools</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">present</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">update_cache</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl">- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Deploy iSCSI configuration</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ansible.builtin.template</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">src</span><span class="p">:</span><span class="w"> </span><span class="l">iscsid.conf.j2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">dest</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/iscsi/iscsid.conf</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">owner</span><span class="p">:</span><span class="w"> </span><span class="l">root</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">group</span><span class="p">:</span><span class="w"> </span><span class="l">root</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">mode</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;0644&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">no_log</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">  </span><span class="c"># the rendered file contains the CHAP password</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl">- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Deploy Multipath configuration</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ansible.builtin.template</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">src</span><span class="p">:</span><span class="w"> </span><span class="l">multipath.conf.j2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">dest</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/multipath.conf</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">owner</span><span class="p">:</span><span class="w"> </span><span class="l">root</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">group</span><span class="p">:</span><span class="w"> </span><span class="l">root</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">mode</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;0644&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">notify</span><span class="p">:</span><span class="w"> </span><span class="l">Reload multipathd</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl">- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Enable and start multipathd</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ansible.builtin.systemd</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">multipathd</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">started</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">enabled</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl">- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Load a changed multipath configuration before logging in</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ansible.builtin.meta</span><span class="p">:</span><span class="w"> </span><span class="l">flush_handlers</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl">- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Discover iSCSI targets</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ansible.builtin.command</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;iscsiadm -m discovery -t st -p {{ item }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">loop</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ iscsi_target_ips }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">register</span><span class="p">:</span><span class="w"> </span><span class="l">iscsi_discovery</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">changed_when</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl">- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Check active iSCSI sessions</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ansible.builtin.command</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;iscsiadm -m session&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">register</span><span class="p">:</span><span class="w"> </span><span class="l">iscsi_sessions</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">changed_when</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">failed_when</span><span class="p">:</span><span class="w"> </span><span class="l">iscsi_sessions.rc not in [0, 21] </span><span class="w"> </span><span class="c"># 21 = no active sessions</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl">- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Log in to iSCSI targets</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ansible.builtin.command</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;iscsiadm -m node -T {{ iscsi_target_name }} -p {{ item }} --login&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">loop</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ iscsi_target_ips }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">when</span><span class="p">:</span><span class="w"> </span><span class="l">(item ~ &#39;:3260&#39;) not in iscsi_sessions.stdout</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">changed_when</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">  </span><span class="c"># only runs for portals without a session</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl">- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Ensure iSCSI login persists across reboots</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ansible.builtin.command</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;iscsiadm -m node -T {{ iscsi_target_name }} -p {{ item }} --op=update --name=node.startup --value=automatic&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">loop</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;{{ iscsi_target_ips }}&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">changed_when</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="w">
</span></span></span></code></pre></div><table>
	<thead>
			<tr>
					<th>Task</th>
					<th>What it does</th>
					<th>Why</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Install packages</td>
					<td><code>open-iscsi</code> and <code>multipath-tools</code></td>
					<td>Initiator and multipath daemon.</td>
			</tr>
			<tr>
					<td>Deploy iSCSI configuration</td>
					<td>Renders <code>iscsid.conf</code></td>
					<td><code>no_log: true</code>: the file contains the CHAP password.</td>
			</tr>
			<tr>
					<td>Deploy Multipath configuration</td>
					<td>Renders <code>multipath.conf</code></td>
					<td>Triggers a reload of <code>multipathd</code> when it changes.</td>
			</tr>
			<tr>
					<td>Enable and start multipathd</td>
					<td>Starts the daemon, enables it at boot</td>
					<td>It must run before the paths appear.</td>
			</tr>
			<tr>
					<td><code>flush_handlers</code></td>
					<td>Runs the reload now</td>
					<td>The new <code>multipath.conf</code> is loaded before the logins.</td>
			</tr>
			<tr>
					<td>Discover iSCSI targets</td>
					<td>Discovery on every portal</td>
					<td>Creates a node record per path.</td>
			</tr>
			<tr>
					<td>Check active iSCSI sessions</td>
					<td>Lists sessions</td>
					<td>Exit code 21 means &ldquo;no sessions&rdquo;, not an error.</td>
			</tr>
			<tr>
					<td>Log in to iSCSI targets</td>
					<td>Logs in per portal</td>
					<td>Skipped for portals that already have a session.</td>
			</tr>
			<tr>
					<td>Ensure login persists</td>
					<td>Sets <code>node.startup</code> to <code>automatic</code> per portal</td>
					<td>All paths come back after a reboot.</td>
			</tr>
	</tbody>
</table>
<h3 id="handlers">Handlers <a class="anchor" data-pagefind-ignore href="#handlers" aria-label="Link to this section">#</a></h3>
<p>One handler: reload <code>multipathd</code> when its config changes. Create <code>handlers/main.yml</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nn">---</span><span class="w">
</span></span></span><span class="line"><span class="cl">- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Reload multipathd</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">ansible.builtin.systemd</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">multipathd</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l">reloaded</span><span class="w">
</span></span></span></code></pre></div><p>Why the handler and the session check matter:</p>
<ul>
<li><strong>Reload, not start.</strong> <code>multipathd</code> is normally already running, so <code>state: started</code> alone never loads a new <code>multipath.conf</code>. The handler reloads it when the template changes, and <code>flush_handlers</code> runs it before the logins.</li>
<li><strong>Skip existing sessions.</strong> <code>iscsiadm --login</code> fails with &ldquo;session already present&rdquo; on a second run. The session check skips portals that are already logged in.</li>
</ul>
<h2 id="templates-for-configuration-files">Templates for configuration files <a class="anchor" data-pagefind-ignore href="#templates-for-configuration-files" aria-label="Link to this section">#</a></h2>
<h3 id="templatesiscsidconfj2">templates/iscsid.conf.j2 <a class="anchor" data-pagefind-ignore href="#templatesiscsidconfj2" aria-label="Link to this section">#</a></h3>
<p>The initiator settings: start <code>iscsid</code> via its socket, log in automatically at boot, authenticate with CHAP, scan for LUNs after login.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-jinja" data-lang="jinja"><span class="line"><span class="cl"><span class="x">iscsid.startup = /bin/systemctl start iscsid.socket
</span></span></span><span class="line"><span class="cl"><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">node.startup = automatic
</span></span></span><span class="line"><span class="cl"><span class="x">node.leading_login = No
</span></span></span><span class="line"><span class="cl"><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">node.session.auth.authmethod = CHAP
</span></span></span><span class="line"><span class="cl"><span class="x">node.session.auth.username = </span><span class="cp">{{</span> <span class="nv">iscsi_chap_username</span> <span class="cp">}}</span><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">node.session.auth.password = </span><span class="cp">{{</span> <span class="nv">iscsi_chap_password</span> <span class="cp">}}</span><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">node.session.scan = auto
</span></span></span></code></pre></div><ul>
<li><code>node.startup = automatic</code>: log in to all discovered paths at boot.</li>
<li><code>node.session.auth.*</code>: CHAP with the credentials from the vault.</li>
<li><code>node.session.scan = auto</code>: scan for LUNs automatically after login.</li>
</ul>
<h3 id="templatesmultipathconfj2">templates/multipath.conf.j2 <a class="anchor" data-pagefind-ignore href="#templatesmultipathconfj2" aria-label="Link to this section">#</a></h3>
<p>This tells <code>multipathd</code> which devices to manage and how to use the paths:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-jinja" data-lang="jinja"><span class="line"><span class="cl"><span class="x">defaults {
</span></span></span><span class="line"><span class="cl"><span class="x">    user_friendly_names yes
</span></span></span><span class="line"><span class="cl"><span class="x">}
</span></span></span><span class="line"><span class="cl"><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">blacklist {
</span></span></span><span class="line"><span class="cl"><span class="x">    wwid &#34;.*&#34;
</span></span></span><span class="line"><span class="cl"><span class="x">}
</span></span></span><span class="line"><span class="cl"><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">blacklist_exceptions {
</span></span></span><span class="line"><span class="cl"><span class="x">    wwid &#34;</span><span class="cp">{{</span> <span class="nv">iscsi_wwid</span> <span class="cp">}}</span><span class="x">&#34;
</span></span></span><span class="line"><span class="cl"><span class="x">}
</span></span></span><span class="line"><span class="cl"><span class="x">
</span></span></span><span class="line"><span class="cl"><span class="x">multipaths {
</span></span></span><span class="line"><span class="cl"><span class="x">    multipath {
</span></span></span><span class="line"><span class="cl"><span class="x">        wwid &#34;</span><span class="cp">{{</span> <span class="nv">iscsi_wwid</span> <span class="cp">}}</span><span class="x">&#34;
</span></span></span><span class="line"><span class="cl"><span class="x">        alias mpatha
</span></span></span><span class="line"><span class="cl"><span class="x">        path_grouping_policy &#34;multibus&#34;
</span></span></span><span class="line"><span class="cl"><span class="x">        path_selector &#34;round-robin 0&#34;
</span></span></span><span class="line"><span class="cl"><span class="x">        failback immediate
</span></span></span><span class="line"><span class="cl"><span class="x">        rr_weight priorities
</span></span></span><span class="line"><span class="cl"><span class="x">        no_path_retry 5
</span></span></span><span class="line"><span class="cl"><span class="x">    }
</span></span></span><span class="line"><span class="cl"><span class="x">}
</span></span></span></code></pre></div><table>
	<thead>
			<tr>
					<th>Setting</th>
					<th>What it does</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>user_friendly_names yes</code></td>
					<td>Names maps <code>mpathN</code> instead of by WWID.</td>
			</tr>
			<tr>
					<td><code>blacklist { wwid &quot;.*&quot; }</code> + <code>blacklist_exceptions</code></td>
					<td>Ignore every device except your iSCSI LUN. Keeps local disks out.</td>
			</tr>
			<tr>
					<td><code>alias mpatha</code></td>
					<td>Fixed name for this LUN: <code>/dev/mapper/mpatha</code>.</td>
			</tr>
			<tr>
					<td><code>path_grouping_policy &quot;multibus&quot;</code></td>
					<td>All paths in one group, so all of them carry I/O.</td>
			</tr>
			<tr>
					<td><code>path_selector &quot;round-robin 0&quot;</code></td>
					<td>Rotate I/O over the paths in the group.</td>
			</tr>
			<tr>
					<td><code>failback immediate</code></td>
					<td>Switch back to the preferred path group as soon as it is available again.</td>
			</tr>
			<tr>
					<td><code>rr_weight priorities</code></td>
					<td>Weight the round-robin by path priority.</td>
			</tr>
			<tr>
					<td><code>no_path_retry 5</code></td>
					<td>When all paths are down, queue I/O for 5 checker intervals, then fail it.</td>
			</tr>
	</tbody>
</table>
<p><strong>Note:</strong> Don&rsquo;t blacklist <code>devnode &quot;^sd[a-z]&quot;</code>: the iSCSI paths are <code>sdX</code> devices as well, and that rule makes multipathd drop the map. The <code>wwid &quot;.*&quot;</code> blacklist with an exception for your LUN keeps local disks out without hiding the iSCSI paths.</p>
<h3 id="finding-the-wwid">Finding the WWID <a class="anchor" data-pagefind-ignore href="#finding-the-wwid" aria-label="Link to this section">#</a></h3>
<p>The template needs the WWID (World Wide Identifier) of the LUN in <code>iscsi_wwid</code>. Retrieve it manually, on a node that is already logged in to the target:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo multipath -ll
</span></span></code></pre></div><p>The WWID is the value between brackets after the map name. Then add it as <code>iscsi_wwid</code> to <code>vars/main.yml</code>.</p>
<h2 id="running-the-ansible-playbook">Running the Ansible playbook <a class="anchor" data-pagefind-ignore href="#running-the-ansible-playbook" aria-label="Link to this section">#</a></h2>
<p>A playbook that applies the role to all hosts. Create <code>setup_iscsi_multipath.yml</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl">- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Setup iSCSI Multipathing</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">hosts</span><span class="p">:</span><span class="w"> </span><span class="l">all</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">become</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">roles</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="l">iscsi_multipath</span><span class="w">
</span></span></span></code></pre></div><p>Run the playbook and enter the vault password when asked:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">ansible-playbook -i inventory setup_iscsi_multipath.yml --ask-vault-pass
</span></span></code></pre></div><p>Or, for unattended runs, with a password file kept outside the repository:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">ansible-playbook -i inventory setup_iscsi_multipath.yml --vault-password-file ~/.vault_pass.txt
</span></span></code></pre></div><p>Thanks to <code>no_log: true</code> on the <code>iscsid.conf</code> task the CHAP password never shows up in the output, not even with <code>-v</code> or <code>--diff</code>.</p>
<h2 id="verifying-the-setup">Verifying the setup <a class="anchor" data-pagefind-ignore href="#verifying-the-setup" aria-label="Link to this section">#</a></h2>
<p>Check that there is one session per path and that both paths are part of one multipath device.</p>
<p><strong>Active iSCSI sessions</strong> (one line per portal):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo iscsiadm -m session
</span></span></code></pre></div><p>Expected output:</p>
<pre tabindex="0"><code>tcp: [1] 192.168.2.253:3260,1 iqn.2025-03.com.example:storage (non-flash)
tcp: [2] 192.168.3.253:3260,1 iqn.2025-03.com.example:storage (non-flash)
</code></pre><p><strong>Multipath devices:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo multipath -ll
</span></span></code></pre></div><p>Expected output:</p>
<pre tabindex="0"><code>mpatha (3600140547f55689de4b49c098d9b1a3c) dm-0 LIO-ORG,iscsi_target
size=20G features=&#39;1 queue_if_no_path&#39; hwhandler=&#39;1 alua&#39; wp=rw
`-+- policy=&#39;round-robin 0&#39; prio=50 status=active
  |- 2:0:0:0 sdb 8:16 active ready running
  `- 3:0:0:0 sdc 8:32 active ready running
</code></pre><p>What to look for:</p>
<ul>
<li><code>mpatha (3600…)</code>: the alias and the WWID.</li>
<li><code>policy='round-robin 0'</code>: both paths are in one group.</li>
<li><code>sdb</code> and <code>sdc</code> both <code>active ready running</code>: both paths work. A failed path shows as <code>failed faulty</code>.</li>
</ul>
<h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Cause / fix</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>multipath -ll</code> shows nothing</td>
					<td>WWID in <code>iscsi_wwid</code> does not match the LUN, so the blacklist hides it. Compare with <code>/lib/udev/scsi_id -g -u -d /dev/sdb</code>.</td>
			</tr>
			<tr>
					<td>Map disappears after a config change</td>
					<td>A <code>devnode &quot;^sd[a-z]&quot;</code> blacklist hides the iSCSI paths. Use the WWID blacklist.</td>
			</tr>
			<tr>
					<td>Only one path in the map</td>
					<td>Login to one portal failed. Check <code>iscsiadm -m session</code> and the network to that portal.</td>
			</tr>
			<tr>
					<td>New <code>multipath.conf</code> has no effect</td>
					<td><code>multipathd</code> was not reloaded. Run <code>systemctl reload multipathd</code>.</td>
			</tr>
			<tr>
					<td>&ldquo;session already present&rdquo;</td>
					<td>Already logged in. The role skips logged-in portals.</td>
			</tr>
	</tbody>
</table>
<h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<ul>
<li>Keep the CHAP credentials in Ansible Vault; <code>no_log: true</code> keeps them out of the output.</li>
<li><code>iscsid.conf</code> on each node holds the CHAP password in plaintext. Consider mode <code>0600</code>.</li>
<li>Put the storage networks on separate VLANs or switches, not on the client network.</li>
<li>Limit LUN access on the target to the expected initiator IQNs.</li>
</ul>
<h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub: <a href="https://github.com/pderuiter/blog-iscsi-multipath-ansible" rel="noopener">pderuiter/blog-iscsi-multipath-ansible</a>. It creates an iSCSI target with a portal on each of two storage networks and an initiator on Proxmox, and applies the <code>iscsi_multipath</code> role from this post with the CHAP secret in Ansible Vault; run <code>terraform apply</code> and then <code>ansible-playbook site.yml --ask-vault-pass</code>.</p>
<h2 id="conclusion">Conclusion <a class="anchor" data-pagefind-ignore href="#conclusion" aria-label="Link to this section">#</a></h2>
<p>With this role every node:</p>
<ul>
<li>Logs in to the target over every path</li>
<li>Keeps its sessions across reboots</li>
<li>Uses one multipath device with failover and load balancing</li>
<li>Gets the same setup as every other node</li>
</ul>
<p>Use <code>/dev/mapper/mpatha</code>, never the <code>sdX</code> paths, for filesystems or LVM.</p>
]]></content:encoded></item><item><title>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>