How to Configure multipath-tools, iSCSI Initiator, and SAN Storage LUNs in Ubuntu Server

Enterprise data centre virtualisation and high-performance database clustering rely on Storage Area Networks (SAN) to deliver centralized block storage across high-speed Ethernet fabrics. In an iSCSI (Internet Small Computer Systems Interface) architecture, compute nodes operate as iSCSI Initiators connecting to remote storage arrays (iSCSI Targets) over standard TCP/IP networks. However, to guarantee enterprise fault tolerance and prevent a single network interface card (NIC), cable snag, or core switch failure from crashing production workloads, SAN storage is plumbed across redundant, independent network fabrics. On Ubuntu Server, connecting to a redundant SAN without Device Mapper Multipathing creates duplicate, competing SCSI device nodes (e.g., /dev/sdb and /dev/sdc for the same physical LUN). By pairing open-iscsi with multipath-tools, administrators coalesce redundant physical paths into a unified, failover-capable block device.

Understanding iSCSI and Device Mapper Multipathing Architecture

Device Mapper Multipath (DM-Multipath) sits between raw SCSI transport drivers and Linux filesystems. When multiple network paths lead to the identical Logical Unit Number (LUN) on a storage array, DM-Multipath aggregates them into a consolidated virtual block device under /dev/mapper/. The table below delineates the core operational components:

System Component	Package Name	Operational Function	Configuration File
iSCSI Initiator	open-iscsi	Encapsulates SCSI commands into TCP/IP packets; establishes target sessions.	/etc/iscsi/iscsid.conf
Initiator Name	open-iscsi	Defines unique iSCSI Qualified Name (IQN) for LUN masking on the SAN array.	/etc/iscsi/initiatorname.iscsi
Multipath Daemon	multipath-tools	Monitors path health, executes failover routing, and manages I/O load balancing.	/etc/multipath.conf
Virtual Device Node	Device Mapper	Presents the aggregated LUN to filesystems (e.g., /dev/mapper/mpatha).	Persistent WWID link in /dev/disk/by-id/

Installing and Initialising Storage Packages

Install the required packages across your Ubuntu Server instance:

sudo apt update && sudo apt install -y open-iscsi multipath-tools

Verify that both background services are active and configured to boot automatically:

sudo systemctl enable --now iscsid multipathd

Configuring the iSCSI Initiator IQN

Storage administrators require your server’s unique iSCSI Qualified Name (IQN) to grant access to target LUNs (a process known as LUN masking).

1. Inspecting the Generated IQN

cat /etc/iscsi/initiatorname.iscsi

The file outputs your unique identifier:

InitiatorName=iqn.2004-10.com.ubuntu:01:4d8a1c92e7

2. Setting a Custom Corporate IQN

If corporate naming conventions require standard nomenclature:

sudo nano /etc/iscsi/initiatorname.iscsi

Modify the entry (e.g., InitiatorName=iqn.2026-10.com.enterprise:db-node-01) and restart the initiator daemon:

sudo systemctl restart iscsid open-iscsi

Discovering and Logging into the SAN Target

With LUN masking configured on the SAN controller, discover available storage portals over your dedicated storage network interfaces.

1. Discovering iSCSI Portals

sudo iscsiadm -m discovery -t sendtargets -p 192.168.10.50

The discovery scan returns the target IQN and available portal IP addresses:

192.168.10.50:3260,1 iqn.2026-10.com.purestorage:flasharray.database-luns
192.168.20.50:3260,2 iqn.2026-10.com.purestorage:flasharray.database-luns

2. Logging into the Target Portals

To establish active TCP sessions across all discovered redundant portals:

sudo iscsiadm -m node -T iqn.2026-10.com.purestorage:flasharray.database-luns --login

Configure automatic reconnects upon operating system reboot:

sudo iscsiadm -m node -T iqn.2026-10.com.purestorage:flasharray.database-luns --op update -n node.startup -v automatic

Running lsblk now reveals multiple block devices (e.g., /dev/sdb and /dev/sdc) displaying identical disk capacities, representing dual network paths to the same backend volume.

Configuring Device Mapper Multipathing

To prevent corruption, Linux must never write directly to raw underlying paths like /dev/sdb; all I/O must route through the coalesced multipath device mapper.

1. Generating /etc/multipath.conf

Create the multipath configuration file using administrative defaults:

sudo nano /etc/multipath.conf

Populate the configuration with recommended enterprise parameters:

defaults {
    user_friendly_names yes
    find_multipaths yes
    polling_interval 10
    path_selector "round-robin 0"
    path_grouping_policy multibus
    path_checker tur
    failback immediate
    rr_min_io 100
    no_path_retry queue
}

blacklist {
    devnode "^(ram|raw|loop|fd|md|dm-|sr|scd|st)[0-9]*"
    devnode "^(hd|xvd|vd)[a-z]"
    devnode "^sda[0-9]*"
}

• user_friendly_names yes: Assigns clean alias handles like /dev/mapper/mpatha.
• path_grouping_policy multibus: Balances I/O actively across all healthy network paths concurrently.
• path_checker tur: Uses SCSI Test Unit Ready commands to monitor path health.
• no_path_retry queue: Prevents application I/O errors during transient network disconnects by queuing writes in memory until a path recovers.

2. Restarting Multipath and Auditing Paths

sudo systemctl restart multipathd
sudo multipath -ll

The console output confirms path aggregation:

mpatha (3624a9370a1b2c3d4e5f6a7b8c9d0e1f2) dm-2 PURE,FlashArray
size=2.0T features='1 queue_if_no_path' hwhandler='0' wp=rw
`-+- policy='round-robin 0' prio=1 status=active
  |- 6:0:0:1 sdb 8:16 active ready running
  `- 7:0:0:1 sdc 8:32 active ready running

Formatting, Mounting, and Preserving via /etc/fstab

Always format and mount the multipath virtual device (/dev/mapper/mpatha) or its unique World Wide Identifier (WWID) link from /dev/disk/by-id/dm-uuid-mpath-....

1. Creating the Filesystem

sudo mkfs.ext4 -L SAN_DATABASE /dev/mapper/mpatha

2. Configuring /etc/fstab with _netdev

Retrieve the filesystem UUID:

sudo blkid /dev/mapper/mpatha

Edit your filesystem table:

sudo nano /etc/fstab

Append the mount record, ensuring the _netdev mount option is specified:

UUID=c4b8e21a-3d2f-4a81-9b11-5e2c8a14d720  /mnt/sandata  ext4  defaults,_netdev  0  2

Critical Role of _netdev: The _netdev flag instructs systemd to delay mounting this filesystem during the boot sequence until all physical network interfaces and iSCSI login sessions are fully established, preventing boot hangs.

Testing Path Failover and Online LUN Resizing

• Simulating Path Failure: Disconnect one physical Ethernet cable or take a storage network interface down (sudo ip link set dev eth2 down). Run sudo multipath -ll: the disconnected path transitions to faulty, while I/O continues uninterrupted across the surviving path without dropping active database transactions.
• Online Volume Expansion: When the storage team expands LUN capacity on the SAN array, rescan your SCSI bus and resize the multipath map online without unmounting the filesystem:

  sudo iscsiadm -m node --rescan
  sudo multipathd resize map mpatha
  sudo resize2fs /dev/mapper/mpatha