iSCSI Multipathing Explained: Paths, Failover, and Linux Setup

iSCSI multipathing gives a server more than one route to the same network storage volume. It is used by Linux administrators and infrastructure teams to keep block storage reachable when a network interface, cable, switch port, or storage-controller path fails. This explainer covers how Linux identifies and combines those paths, what failover can and cannot protect, and how to verify a deployment before trusting it with production data.

What Is iSCSI Multipathing?

iSCSI carries SCSI block commands over TCP/IP. A storage array, NAS, or software target presents a logical unit (LUN); an initiator logs in to the target and the operating system exposes the LUN as a block device. The iSCSI protocol specification, RFC 7143, describes sessions and their TCP connections. Multipathing operates at a different layer: it gives the host multiple SCSI paths to the same LUN and presents those paths through one stable device.

On Linux, device-mapper multipath (DM-Multipath) groups paths that have the same device identity and creates one stable mapped device. Applications and filesystems use that device rather than choosing one underlying /dev/sdX path. When one path becomes unavailable, the multipath stack can route I/O over another usable path, subject to the array, host configuration, and workload.

The Problem iSCSI Multipathing Solves

A single iSCSI session over one NIC and one switch path has a single route to the LUN. A cable failure, NIC fault, switch maintenance, or target-port outage can interrupt storage I/O even if the storage itself remains healthy. Reconnecting the session may restore access, but it can take time and interrupt applications.

Adding paths can reduce this dependency, but only when the paths are genuinely independent and all lead to the same LUN. Two portal addresses routed through the same switch, NIC, or controller do not protect against failure of that shared component. Multipathing also does not protect against LUN deletion, array-wide failure, accidental writes, or data corruption; snapshots and backups address different risks.

How It Works: Paths, Maps, and Failover

Each path is an end-to-end SCSI route from the host to a target port and LUN. With iSCSI, paths commonly use distinct initiator interfaces and target portals, often across separate network fabrics. The initiator logs in to the portals, and Linux discovers the resulting SCSI devices. The multipath tools identify paths for the same LUN by its worldwide identifier (WWID), then create a device-mapper map that applications can use.

The Linux kernel’s device-mapper layer holds the map and directs I/O. The userspace multipathd daemon monitors path health and updates the map as paths appear, fail, recover, or change state. The Debian multipath(8) manual documents map creation and path-selection behavior; the SUSE multipath guide discusses configuration and array path states.

Arrays do not all make every path equally usable. With Asymmetric Logical Unit Access (ALUA), a target can report paths as optimized, non-optimized, or unavailable. The host should prefer paths according to the array’s reported state and its vendor-supported configuration. A path selector can distribute I/O among eligible paths, but the policy is not a substitute for the target’s path priorities.

What happens when a path fails?

When a path stops responding, the host’s SCSI and iSCSI layers detect the problem according to their timeouts and recovery settings. multipathd can then mark that path unusable and the map can send new I/O through another eligible path. Existing I/O may still take time to recover while the transport and target finish error handling, so failover is not necessarily instantaneous.

The outcome also depends on the state of the remaining paths. If every path is unavailable, the multipath configuration determines whether I/O waits for a path to return or fails back to the application. Applications may therefore pause or report errors during an outage even when individual path failover works correctly. Review queue and retry settings with the array vendor, and test the expected behavior with the actual filesystem and workload. When a path returns, its ALUA state and failback policy determine whether it resumes carrying I/O.

The RFC’s session model allows multiple TCP connections in a session, but that is not a guarantee of independent host-side block paths. DM-Multipath works with distinct SCSI paths; whether a particular target and initiator configuration can provide them depends on the devices and topology.

Components and Key Concepts

• Initiator and target: The initiator is the host-side iSCSI client; the target exports LUNs through one or more network portals.
• Path: One discovered SCSI route to a LUN. A path includes more than an IP address: host interface, network route, target port, and storage-controller state all matter.
• WWID: A persistent identifier used to recognize that multiple discovered devices refer to the same LUN. Multipath must not combine unrelated LUNs.
• Multipath map: The device-mapper block device used by filesystems and applications. Prefer this device over an individual /dev/sdX path.
• multipathd: The daemon that monitors paths and manages map changes.
• ALUA and path selector: ALUA communicates target-side access states; a selector determines how I/O is distributed across paths the target makes usable.

Real-World Use Cases

Virtualization hosts can use multipath to keep access to shared iSCSI datastores during a planned switch-port outage or a failed network adapter. Database servers and other block-storage consumers can maintain access when one target port or network route is lost. In both cases, the design must include redundant links and switches on the host side and redundant target ports or controllers on the storage side.

Multipathing can also distribute I/O across active paths when the storage array supports that behavior. It does not guarantee that a single application request becomes faster, nor that bandwidth adds up linearly: the array’s controller design, path policy, queue depths, workload, and network capacity all constrain throughput.

Getting Started: Configure and Verify on Linux

The following example uses a Debian or Ubuntu initiator and two reachable target portals. Replace the example IQN and addresses with values provided by the storage administrator. Before connecting, confirm that both portals export the same LUN and that the network paths are intended to be independent.

Install the initiator and multipath tools, then start their services:

sudo apt update
sudo apt install open-iscsi multipath-tools
sudo systemctl enable --now iscsid multipathd

Discover and log in to each portal for the same target. Follow the array’s authentication and interface-binding guidance if it requires CHAP or specific initiator interfaces:

sudo iscsiadm -m discovery -t sendtargets -p 192.0.2.10:3260
sudo iscsiadm -m node -T iqn.2001-04.example:storage01 -p 192.0.2.10:3260 --login
sudo iscsiadm -m node -T iqn.2001-04.example:storage01 -p 192.0.2.20:3260 --login

Wait for device discovery, then inspect both the iSCSI sessions and multipath maps:

sudo iscsiadm -m session -P 3
sudo multipath -ll
ls -l /dev/mapper/

Confirm that the map lists the expected number of paths for one WWID and that their states match the array’s design. Do not format, mount, or give an application an individual /dev/sdX path. Use the stable multipath map after confirming it represents the intended LUN.

Most deployments should start with their Linux distribution’s and array vendor’s recommended defaults. If a stable local alias is needed, add a multipaths entry to /etc/multipath.conf using the actual WWID reported for the LUN; do not copy an example WWID:

defaults {
    find_multipaths yes
}

multipaths {
    multipath {
        wwid 3600a0980000000000000000000000001
        alias data01
    }
}

After editing the configuration, ask the daemon to reload it and inspect the map again:

sudo multipathd reconfigure
sudo multipath -ll

Test failover only in a controlled maintenance window or a lab. Start a representative, monitored I/O workload, take one approved path out of service using the storage or network team’s procedure, and confirm that the map continues on the remaining path. Restore the path and verify recovery. Never test by disabling a shared interface or logging out sessions unless you have positively identified which paths will be affected.

For initial diagnosis, compare multipath -ll with iscsiadm -m session -P 3, and review journalctl -u multipathd and journalctl -u iscsid. A missing path may be an iSCSI login, network reachability, target ACL, or array-state problem; a missing map may indicate that devices have different WWIDs or that the host is not configured to claim them. The upstream multipath-tools project provides the Linux multipath utilities and their source.

Common Misconceptions

• “Two IP addresses guarantee redundancy.” They do not if both routes share a NIC, switch, power domain, or storage controller. Map the actual failure domains.
• “Multipathing is the same as bonding or iSCSI multiple connections.” These mechanisms act at different layers. Configure and verify multiple SCSI paths if the requirement is block-device failover.
• “More paths always mean more speed and safety.” Paths may be standby or non-optimized, and performance depends on the array and workload. Multipathing is not a backup, replication system, or multi-host filesystem.

Related Articles

• iSCSI SAN implementation and target design
• iSCSI vs. NFS vs. SMB storage protocols
• Block storage performance and tuning
• SMB Multichannel and network path redundancy

Changelog

• Initial publication.

Last updated: 2026-09-25