Inspect and Safely Operate multipathd with multipathc

multipathc opens an interactive shell straight into multipathd, live paths and all. This guide gives you a repeatable way through it: connect, inspect paths and maps, print useful topology, and keep read-only checks firmly separate from the commands that can actually move I/O. The examples match multipath-tools 0.9.4-5ubuntu8.2, whose client identifies itself as v0.9.4.

Allow about fifteen minutes. You need a Linux host using multipath-tools and a running multipathd daemon. Most inspection commands are ordinary commands, but storage administration normally needs elevated privileges and a maintenance procedure. This guide does not change queueing, fail paths, reload maps or reconfigure a daemon.

1. Confirm the installed client

Check which executable your shell will run and record the package version. These checks are read-only:

$ command -v multipathc
/usr/sbin/multipathc
$ dpkg-query -W -f='${Package} ${Version}\n' multipath-tools
multipath-tools 0.9.4-5ubuntu8.2

The installed manual describes multipathc as an interactive client for multipathd. It also says that multipathd -k invokes the same kind of shell. Keep the client and daemon versions aligned where possible, especially when copying command examples between hosts.

Checkpoint: You have confirmed the binary and package version before troubleshooting its output.

2. Open a read-only inspection session

Start the shell without sudo first. The optional argument is a reply timeout in milliseconds; the default is 4000 ms. A longer timeout can help on a busy host, but it does not start the daemon or make an unavailable socket healthy.

$ multipathc 8000
> show status
> show daemon
> quit

Use quit, exit or Ctrl-D to leave. On the installed build, commands can be abbreviated by their initial letters when the abbreviation is unique. Prefer full commands in runbooks: they are easier to review and less likely to become ambiguous after an upgrade.

If the session cannot get a reply, check the daemon and its service logs before trying storage commands. A timeout is a reason to diagnose the control path, not a reason to repeat a potentially disruptive operation.

3. Check paths and maps before interpreting topology

Ask what multipathd is monitoring. These commands only display state:

> list paths
> list maps
> list maps status
> list status
> list topology

The command names also accept show, so show paths and show topology are equivalent forms documented by the manpage. The exact rows depend on the host. A host with no monitored paths can legitimately report an empty result: do not treat a missing map as proof a disk is safe to remove.

list status summarises path-checker states, monitored paths and whether multipathd is handling a uevent. list maps status reports map status, while list maps topology gives the detailed path-group view. Capture these before and after any approved change so you can see what actually moved.

Checkpoint: You know the map name or WWID, the paths belonging to it, and whether the daemon is busy handling an event.

4. Make output useful with format wildcards

Long topology output is not always the best diagnostic record. First ask the client which placeholders this build supports:

> show wildcards

For maps, useful fields include %n for the name, %w for the UUID, %N for the path count, %S for size and %Q for queueing. For paths, %d is the device name, %o the device state, %T the checker state, %m the multipath map and %z the serial.

For example, request a compact map report:

> list maps format %n %w %N %Q %S

And request a compact path report:

> list paths format %d %o %T %m %z

Format strings are arguments to the multipathd command, not shell variables. When using the one-shot form from a shell, quote the command so shell metacharacters and whitespace stay together:

$ multipathd -k'show topology'

The shell form is easier for several related queries; the one-shot form is convenient for a single capture. The daemon must already be running for either form to return live state.

5. Inspect configuration without editing it

Use the daemon's view when you need to know what it is actually using:

> list config
> list config local
> list blacklist
> list devices

list config shows the effective configuration derived from defaults and /etc/multipath.conf. list config local limits its devices section to devices present on this system. list blacklist shows effective blacklist rules, and list devices includes whether available block devices are blacklisted.

These reports answer different questions. A device can be present but blacklisted; a path can exist without being part of the map you expected; and an effective value can come from a default rather than the line you last edited. Save the relevant output before changing configuration.

6. Treat operational commands as a warning boundary

The interactive shell also exposes commands that change live storage behaviour. Examples include fail path, reinstate path, suspend map, resume map, reload map, reconfigure, disablequeueing and shutdown. The presence of a command in help is not approval to use it.

Before running one, identify the exact path or map and confirm the change with the storage owner. A failed path or suspended map can remove redundancy or interrupt I/O. A reconfiguration can reload changed devices, and reconfigure all reloads every multipath device regardless of whether it changed. Do not test these commands on a production map merely to learn their syntax.

Warning: there is no universal undo for a storage mistake. Some actions have a corresponding command, such as reinstate path after an approved fail path, or resume map after suspend map, but the underlying device state and outstanding I/O still matter. Keep a console or out-of-band path available, record the pre-change output, and follow your site's rollback procedure. If you only need evidence, stay with list and show commands.

7. Verify the session and leave it cleanly

End an inspection session explicitly and capture a final status if you are working during an incident:

> show status
> exit
$ printf 'client exit status: %s\n' "$?"
client exit status: 0

A successful client exit means the shell ended normally. It does not certify that every path is healthy. Use the saved path, map and daemon reports to verify the condition you actually care about, and compare them with the host's monitoring and multipath logs.

Done means