How to Configure Ubuntu Server Multipath I/O (MPIO) for Redundant iSCSI SAN Connections

In enterprise data centre environments, connecting an Ubuntu Server to a Storage Area Network (SAN) via iSCSI is standard practice. However, a single network connection to a critical storage volume introduces an unacceptable single point of failure. If the network switch fails, the Ethernet cable is severed, or a specific network interface card (NIC) on the storage array goes offline, the Ubuntu server will immediately lose access to its disk, resulting in catastrophic application crashes. To achieve high availability and continuous storage access, administrators must configure redundant network paths and manage them using Linux Multipath I/O (MPIO).

The Principle of Multipathing

When an Ubuntu server is connected to an iSCSI SAN using multiple network interfaces, the Linux kernel discovers the same physical storage LUN (Logical Unit Number) multiple times—once for every available network path. Without multipathing software, the OS sees these duplicate paths as entirely separate hard drives (e.g., /dev/sdb, /dev/sdc, /dev/sdd), leading to severe data corruption if the file system attempts to write to them concurrently.

The multipath-tools package solves this by intercepting the duplicate block devices and aggregating them into a single, highly available virtual device (e.g., /dev/mapper/mpatha). Applications read and write exclusively to this virtual device, while the multipath daemon handles load balancing and transparent failover across the underlying physical paths.

Installing and Enabling Multipath Tools

First, ensure your iSCSI initiator is fully configured and that the Ubuntu server can see the storage volume across at least two distinct IP subnets or network interfaces. Once confirmed, install the multipath daemon.

sudo apt update
sudo apt install multipath-tools

By default, Ubuntu does not automatically enable multipathing for all devices. You must generate a default configuration file and explicitly enable the service.

sudo mpathconf --enable --with_multipathd y

Configuring the multipath.conf File

The core configuration file is located at /etc/multipath.conf. While the default settings are sufficient for basic failover, enterprise arrays (like Dell EqualLogic, NetApp, or Pure Storage) require specific tuning to optimise how the server handles path failures and load balancing.

Open the file and locate the defaults section. A standard, robust configuration looks like this:

defaults {
    user_friendly_names yes
    find_multipaths yes
    path_grouping_policy multibus
    path_checker tur
    failback immediate
    no_path_retry queue
}

• user_friendly_names: Assigns easy-to-read names like mpatha instead of long WWID hashes.
• path_grouping_policy multibus: Instructs the daemon to use all available active paths simultaneously for load balancing (Active/Active), rather than keeping one path idle (Active/Passive).
• path_checker tur: Uses the “Test Unit Ready” SCSI command to continuously verify if a path is alive.
• no_path_retry queue: If all paths fail simultaneously (e.g., a total SAN outage), the OS will queue I/O requests in memory rather than immediately failing the filesystem. This prevents kernel panics during brief network blips.

Blacklisting Local Drives

A critical step is ensuring the multipath daemon ignores your local internal hard drives (like the OS boot disk). If multipath attempts to manage the local NVMe or SATA drive, it can cause severe boot issues. Modify the blacklist section to exclude local device types:

blacklist {
    devnode "^(ram|raw|loop|fd|md|dm-|sr|scd|st)[0-9]*"
    devnode "^sda"
    device {
        vendor "VMware"
        product "Virtual disk"
    }
}

Applying and Verifying the Configuration

After saving the configuration file, restart the multipath daemon to apply the changes.

sudo systemctl restart multipathd

To verify that the Ubuntu server has successfully aggregated the duplicate iSCSI paths into a single virtual device, run the multipath topology command:

sudo multipath -ll

The output should display the friendly name (e.g., mpatha), the WWID of the volume, and a tree structure showing the underlying physical paths (e.g., sdb, sdc). If configured for multibus, all paths should display a status of active ready. If you physically disconnect one of the network cables, running the command again will instantly show one path as failed, while the virtual mpatha device remains online, ensuring zero disruption to your running applications.