Post

iSCSI and Multipath on Linux: Connecting to Network Block Storage

iSCSI and Multipath on Linux: Connecting to Network Block Storage

NFS and Samba share files; iSCSI shares block devices over an ordinary IP network, and the client treats the result exactly like a local disk — partition it, format it, put LVM on top of it, whatever you’d do with a local drive. This post covers connecting to an iSCSI target and using multipath to survive a single network or controller failure.

iSCSI Terminology

Before touching a command, the four terms that show up everywhere: the target (the storage being shared), the initiator (the client connecting to it), the IQN (iSCSI Qualified Name, a unique identifier for each side), and the portal (the target’s IP:port, usually 3260).

1
2
# A typical IQN format
iqn.2012-12.com.example:storage.target01

Tip: IQNs are globally meant to be unique, built from a reversed domain name and a date the domain was controlled, exactly like Java package naming. You rarely need to construct one by hand — iscsiadm generates your initiator’s IQN automatically on first install.

Installing the Initiator

The client-side package is open-iscsi (Debian/Ubuntu naming) or iscsi-initiator-utils (RHEL family), both built around the same iscsiadm CLI.

1
2
3
4
5
6
sudo apt install open-iscsi             # Debian/Ubuntu
sudo dnf install iscsi-initiator-utils  # RHEL/CentOS/Fedora

# Your initiator's generated IQN
cat /etc/iscsi/initiatorname.iscsi
# InitiatorName=iqn.1993-08.org.debian:01:a1b2c3d4e5f6

Tip: If you’re cloning VM images, this initiator name gets cloned too — two machines with the same IQN will confuse a target that does per-initiator access control. Regenerate it on clones with iscsi-iname.

Discovering Targets

Discovery asks a portal what targets it’s willing to export, before you commit to logging into any of them.

1
2
3
4
5
sudo iscsiadm -m discovery -t sendtargets -p 10.0.0.50:3260
# 10.0.0.50:3260,1 iqn.2012-12.com.example:storage.target01

# Discovered targets are cached locally
sudo iscsiadm -m node

Tip: Discovery doesn’t grant access by itself — it just tells you what’s visible from this portal. Actual access control is enforced separately, often via IP-based ACLs or CHAP authentication configured on the target.

Logging Into a Target

Logging in establishes the session and, on success, hands you a new local block device, exactly as if you’d plugged in a drive.

1
2
3
4
5
6
sudo iscsiadm -m node -T iqn.2012-12.com.example:storage.target01 -p 10.0.0.50:3260 --login
# Logging in to [iface: default, target: iqn.2012-12.com.example:storage.target01, portal: 10.0.0.50,3260]
# Login to [...] successful.

lsblk
# sdc    8:32   0   500G  0 disk

Tip: The new device name (/dev/sdc here) isn’t guaranteed to be stable across reboots if other disks come and go. Reference the LUN by its /dev/disk/by-path/ or /dev/disk/by-id/ symlink in /etc/fstab, not the raw /dev/sdX name.

Making the Login Persistent

By default, a login doesn’t survive a reboot unless the node is marked to connect automatically at boot.

1
2
3
sudo iscsiadm -m node -T iqn.2012-12.com.example:storage.target01 -p 10.0.0.50:3260 --op=update -n node.startup -v automatic

sudo systemctl enable iscsid open-iscsi

Tip: node.startup=automatic only reconnects targets already discovered and logged into once. On a freshly rebuilt host, you still need to run discovery and the first login manually before this setting has anything to act on.

Why Multipath Matters

A single iSCSI session over a single NIC and a single network path is a single point of failure — lose that link, and the storage disappears mid-operation. Multipath presents the same LUN reached over multiple independent paths as one resilient device.

1
2
3
4
# Two NICs, two portals, same target = two independent paths to the same LUN
sudo iscsiadm -m discovery -t sendtargets -p 10.0.0.50:3260
sudo iscsiadm -m discovery -t sendtargets -p 10.0.1.50:3260
sudo iscsiadm -m node --login

Tip: Multipath redundancy requires genuinely separate paths — different NICs, different switches ideally, different target controller ports. Two sessions over the same single NIC give you two device names but not real redundancy.

Configuring multipath-tools

With both sessions logged in, lsblk shows the same underlying LUN as two separate device names; multipath is what merges them back into one.

1
2
3
4
5
sudo apt install multipath-tools   # Debian/Ubuntu
sudo dnf install device-mapper-multipath  # RHEL/CentOS/Fedora

sudo mpathconf --enable --with_multipathd y
sudo systemctl enable --now multipathd

Tip: multipath -t prints the compiled-in default config, which is a solid starting point to understand the format before you write a custom /etc/multipath.conf.

Checking Path Status

multipath -ll is the command to learn by heart — it shows every path to every multipathed device and whether each one is active or failed.

1
2
3
4
5
6
7
sudo multipath -ll
# mpatha (36001405...) dm-2 LIO-ORG,TARGET01
# size=500G features='0' hwhandler='1 alua' wp=rw
# |-+- policy='service-time 0' prio=50 status=active
# | `- 3:0:0:0 sdc 8:32 active ready running
# `-+- policy='service-time 0' prio=10 status=enabled
#   `- 4:0:0:0 sdd 8:48 active ready running

Tip: status=active on one path group and status=enabled on another is normal with an ALUA-aware target — it means one path is preferred and the other is standby, not broken. Both show ready running when healthy.

Using the Resulting Device

The multipathed device appears under /dev/mapper/, and from here on it’s treated exactly like any other block device — partition, format, mount, or hand to LVM.

1
2
3
4
5
6
7
8
ls /dev/mapper/
# mpatha

sudo mkfs.xfs /dev/mapper/mpatha
sudo mount /dev/mapper/mpatha /mnt/san-storage

# Reference by the stable mapper name in /etc/fstab, never /dev/sdc directly
echo "/dev/mapper/mpatha /mnt/san-storage xfs defaults,_netdev 0 0" | sudo tee -a /etc/fstab

Tip: The _netdev mount option tells the init system this filesystem depends on the network being up first. Omitting it on a network-backed block device is a classic cause of boot hangs or mount failures on restart.

This post is licensed under CC BY 4.0 by the author.