Multipath on Linux: Inspect Paths, Name Maps and Reload Safely

You will finish with a read-first workflow for Linux device-mapper multipath: inspect the paths the host can see, understand why a map was or was not created, give a known LUN a stable name, and verify a configuration reload. The examples match multipath-tools 0.9.4-5ubuntu8.2 and its multipath 0.9.4 command on this machine.

Allow about 20 minutes for inspection, or longer if you need to identify a storage vendor's recommended settings. You need a shell, the multipath-tools package, and access to the SAN or other storage paths you intend to manage. Read-only inspection is usually available to ordinary users, but map inspection, configuration changes and reloads normally need root.

1. Confirm the installed command

Start with the local binary rather than copying an option from a different release:

$ command -v multipath
/usr/sbin/multipath
$ multipath -h
multipath-tools v0.9.4 (12/19, 2022)

The default operation can create or update device-mapper maps. Do not begin with a bare multipath command on a production host. Use the dry-run option while you are learning what the host detects.

Checkpoint: if the version is not the one shown above, keep the installed command's help and manpages beside you. Defaults and supported options are package-version details.

2. Inspect discovery without creating maps

Run a verbose dry run. This prints detected paths and candidate topology but does not create or update device maps:

$ sudo multipath -d -v3 2>/tmp/multipath-discovery.err
# detected paths and candidate maps appear on standard output

The -d option is the safety boundary here. The manpage also documents that -v3 prints all detected paths and map topology. The temporary error file keeps diagnostics separate from the useful output; inspect it if the command reports a problem:

$ sed -n '1,120p' /tmp/multipath-discovery.err

Look for repeated WWIDs. A WWID is the identifier multipath uses to decide which paths belong to the same device. The same storage LUN can therefore appear as several ordinary block devices while one multipath map represents it above them.

Checkpoint: do not continue until you can identify the WWID you expect to manage. If there are no repeated WWIDs, the host may have one path only, the paths may expose different identifiers, or a blacklist may exclude them.

3. Read the effective configuration

There are two useful configuration views:

$ sudo multipath -t
# effective multipathd configuration, including built-in defaults
$ sudo multipath -T
# effective configuration limited to devices present on this host

multipath.conf is not just a list of local preferences. The built-in hardware table supplies device-specific values, then configuration sections override one another. The -T output is especially useful as a starting point for a real configuration because it shows settings relevant to hardware that is actually present.

On this installed package, /etc/multipath.conf enables user_friendly_names yes. The resulting alias is allocated through /etc/multipath/bindings, normally as a name such as mpath0. That name is convenient, but it is not the best long-term identifier for an important LUN: bindings can change when the file is not carried into an initramfs or when maps are discovered in a different order.

The installed daemon also reports find_multipaths on in its effective configuration. In the 0.9.4 manpage, the documented choices are strict, no, yes, greedy and smart; distributions may translate a compatibility value such as on into the same policy as yes. Use multipath -t on the host you are changing instead of guessing from a generic example.

4. Give one known WWID a stable alias

For a production LUN, prefer an explicit alias tied to its exact WWID. First save the current file. This is an elevated, persistent change, so stop if you are unsure which host or LUN you are editing:

$ sudo cp -a /etc/multipath.conf /etc/multipath.conf.before-lun-alias

Edit /etc/multipath.conf and add a multipaths section. Replace both placeholder values with the exact WWID from your discovery output. The WWID in this section is an exact match, not a regular expression:

multipaths {
    multipath {
        wwid 3600508b400105e210000900000490000
        alias finance_data_01
    }
}

The alias becomes the map name, commonly available below /dev/mapper/finance_data_01. Keep aliases unique, stable and meaningful without embedding a secret or an assumption about which host owns the LUN. Do not use a guessed WWID. A wrong alias can make an operator address the wrong storage device.

Configuration syntax is strict enough to catch many mistakes, but a syntactically valid file can still describe the wrong storage. Compare the rendered configuration and the target WWID before reloading:

$ sudo multipath -t | sed -n '/multipaths {/,/^}/p'
$ sudo multipath -T | grep -A8 -B2 'finance_data_01'

If the backup needs restoring, use the saved copy and then repeat the read-only checks:

$ sudo cp -a /etc/multipath.conf.before-lun-alias /etc/multipath.conf
$ sudo multipath -t

5. Reload and verify the map

Once the output is correct and the storage team has confirmed the alias, ask the daemon to reload existing maps:

$ sudo multipath -r

The -r operation is delegated to multipathd when it is running, and other multipath switches do not affect that operation. This is still a live storage change. Perform it during an approved maintenance window if the LUN carries important I/O.

Inspect the resulting topology with maximum available detail:

$ sudo multipath -ll finance_data_01
# expect the alias, WWID, path groups, path devices and live states

Output is hardware-specific. A healthy map normally shows the expected WWID and more than one path, with paths reported as usable or live. A map with a missing path is not automatically safe: it may still serve I/O while protection against another failure is reduced.

For a separate health check, test whether the map has usable paths. This does not perform I/O:

$ sudo multipath -C finance_data_01
$ printf 'multipath check status: %s\n' "$?"

Keep the status immediately after the command. A non-zero result needs investigation before you treat the map as ready for applications.

6. Avoid the common failure modes

One path is present. With find_multipaths enabled, a single non-blacklisted path may not be enough to create a new map. Confirm zoning, target presentation and WWID values before changing policy. multipath -i can ignore the WWIDs file in limited modes, but the manpage calls this a rare-use override. It is not a general repair command.

The device is blacklisted. Check the blacklist and blacklist_exceptions sections, plus the detected vendor, product and protocol. Regular expressions in multipath.conf are case-sensitive and unanchored, so an expression such as bar also matches barbie. Anchor patterns with ^ and $ when you need an exact boundary.

All paths are down. Do not casually enable queue_if_no_path or no_path_retry queue. The local manpage warns that indefinite queueing can leave processes stuck in uninterruptible sleep, and queued I/O can interact badly with device removal. The default no_path_retry fail is a deliberate safety boundary, not a missing feature.

You are tempted to flush maps. multipath -f DEVICE removes one unused map, while multipath -F removes all unused maps. These are destructive to the current device-mapper presentation and may disrupt applications or mounts. Do not run either command until you have verified that the map is unused and have an approved recovery plan.