Inspect and Safely Operate Linux Multipath with multipathd

One of your storage paths has gone quiet, and multipathd can tell you whether it matters. By the end of this guide you can inspect the paths and device maps it watches, check its effective configuration, reload a change, and recognise which commands can actually interrupt I/O.

Before you start

You need a Linux host using the multipath-tools package, a shell, and an account allowed to read the multipath command socket. Most operational commands should be run with sudo. Have the WWID, alias, or device-mapper name of the map you intend to inspect before changing anything.

This guide uses the locally installed multipathd(8) from multipath-tools version 0.9.4-5ubuntu8.2. The service and configuration details can differ between package releases. Allow about 10 minutes for inspection. A configuration change or path recovery can take longer because it depends on the storage array and its failover behaviour.

1. Confirm the daemon and package

Start by checking the installed version and whether systemd considers the daemon active. These checks do not alter multipath devices.

dpkg-query -W -f='${Package} ${Version}\n' multipath-tools
systemctl is-active multipathd.service
systemctl status --no-pager multipathd.service

Expected output includes the package name and version, followed by active when the service is running. A failed or inactive service does not by itself prove that storage is unavailable: inspect the paths and recent service log before restarting it.

sudo journalctl -u multipathd.service -n 50 --no-pager

2. Inspect paths, maps, and the daemon

multipathd has a client mode. The command string follows -k with no space. Quote commands containing spaces so your shell passes them as one argument.

sudo multipathd -k 'show daemon'
sudo multipathd -k 'show status'
sudo multipathd -k 'show paths'
sudo multipathd -k 'show maps'
sudo multipathd -k 'show topology'

show daemon reports the daemon state. show status summarises path-checker states, monitored paths, and current uevent handling. show paths lists the paths being monitored, while show maps lists the multipath devices. The topology view is equivalent to multipath -ll and shows how paths are grouped beneath each map.

Use the map identifier returned by show maps in later commands. It may be a device-mapper name such as dm-0, an alias such as mpath1, or a WWID such as 36005076303ffc56200000000000010aa.

3. Check the effective configuration

The daemon combines built-in defaults with /etc/multipath.conf. Ask the running daemon what it is actually using rather than relying on an assumption about defaults.

sudo multipathd -k 'show config'
sudo multipathd -k 'show config local'
sudo multipathd -k 'show blacklist'
sudo multipathd -k 'show devices'

show config displays the effective configuration. The local variant limits its devices section to devices present on this host. show blacklist exposes the effective blacklist rules, and show devices shows available block devices together with their blacklist status.

Read /etc/multipath.conf before editing it, and keep a copy of any working version outside the editor. A small blacklist or find_multipaths change can alter which devices become maps. Do not copy a configuration from another host without checking vendor, WWID, path policy, and reservation settings.

4. Reload a configuration change

After editing the configuration, validate the intended result through the daemon before treating the change as complete. The reconfigure command rereads the configuration and reloads changed maps.

sudo multipathd -k reconfigure
sudo multipathd -k 'show config'
sudo multipathd -k 'show topology'

Successful output is implementation-dependent, so use the follow-up queries as verification: the effective setting should be present, and the expected maps and path groups should still be visible. The same reread happens when the service starts, when it is reloaded, or after a SIGHUP.

To undo a configuration-only change, restore the last known-good /etc/multipath.conf and run sudo multipathd -k reconfigure again. If the change created an unwanted map or altered path selection, stop and compare show config, show blacklist, and show topology before taking further action.

5. Handle a path problem with a narrow command

Manual path commands are for controlled diagnosis or recovery. They affect what the daemon monitors and can change I/O availability. First inspect the path name using show paths, then substitute that exact name.

sudo multipathd -k 'fail path PATH_DEVICE'
sudo multipathd -k 'show paths'
sudo multipathd -k 'reinstate path PATH_DEVICE'

Replace PATH_DEVICE with a real name such as sda. The first command marks that path failed; the second checks its state; the third returns it from failed state. Do not use this sequence as a generic test on production storage. A failed path may cause traffic to move to another path, and reinstating a path whose transport is still broken may create repeated errors.

add path and remove path change the monitored path list. add map and remove map do the same for maps. Use them only when you understand why automatic discovery did not produce the desired state, and verify with show paths or show maps immediately afterwards.

Commands to treat as service-impacting

Several interactive commands can change I/O behaviour and are not routine inspection:

• suspend map MAP suspends a map; resume map MAP resumes it.
• reload map MAP reloads a device, and resize map MAP changes its size.
• switchgroup map MAP group NUMBER forces a path-group choice.
• disablequeueing map MAP or its maps-wide form changes what happens when paths are unavailable.
• shutdown stops multipathd. It is not an ordinary way to apply configuration.

Use these only with a tested recovery plan and storage-owner approval. For an accidental suspend, use the matching resume map MAP command after confirming the map identifier. For a stopped daemon managed by systemd, use sudo systemctl restart multipathd.service only after checking the service log and current topology; restarting a storage service is a disruptive recovery action, not a harmless retry.

Common traps

• A space after -k. multipathd -k'show topology' is the documented form. Keep the command attached to -k.
• Confusing a path with a map. sda is a path; dm-0, an alias, or a WWID identifies a map.
• Assuming the local file is the whole configuration. Defaults and package behaviour also contribute. Check show config.
• Using the obsolete -n option. The installed manpage marks it ignored. Configure find_multipaths in multipath.conf instead.
• Running as an unprivileged account. A command can fail while the daemon itself is healthy if the client cannot read its socket or configuration directories. Retry the read-only query with sudo.