Skip to content

multipath.8: document output format for -l/-ll options #131

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
anatoliiohorodnyk wants to merge 1 commit into
base: master
Choose a base branch
from
+109 −1
Open

multipath.8: document output format for -l/-ll options #131

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/actions/spelling/expect.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,13 +123,15 @@
linux
LIO
lpthread
lun
Copy link
Collaborator

@mwilck mwilck Jan 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just replace "Lun" with "lun". Or better even, use "LUN" in your text. After all, it's an acronym for "Logical Unit Number".

Lun

Check warning on line 127 in .github/actions/spelling/expect.txt

View workflow job for this annotation

GitHub Actions / Check Spelling 

`Lun` is ignored by check-spelling because another more general variant is also in expect. (ignored-expect-variant)
lvm
lvmteam
Lyve
Marzinski
misdetection
mpath
mpatha
mpathb
mpathpersist
mpathvalid
Expand All @@ -145,7 +147,7 @@
nompath
NOSCAN
Nosync
NVMe

Check warning on line 150 in .github/actions/spelling/expect.txt

View workflow job for this annotation

GitHub Actions / Check Spelling 

`NVMe` is ignored by check-spelling because another more general variant is also in expect. (ignored-expect-variant)
nvme
NFINIDAT
OBJDEPS
Expand Down Expand Up @@ -198,6 +200,7 @@
scsi
SCST
sda
sdb
Seagate
setmarginal
setprkey
Expand Down
107 changes: 106 additions & 1 deletion multipath/multipath.8.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
.\" Update the date below if you make any significant change.
.\" ----------------------------------------------------------------------------
.
.TH MULTIPATH 8 2023-09-08 Linux
.TH MULTIPATH 8 2025-12-31 Linux
.
.
.\" ----------------------------------------------------------------------------
Expand Down Expand Up @@ -275,6 +275,111 @@ Number of times to retry flushing multipath devices that are in use. The default
is \fI0\fR.
.
.\" ----------------------------------------------------------------------------
.SH "OUTPUT FORMAT"
.\" ----------------------------------------------------------------------------
.
The \fB-l\fR and \fB-ll\fR options display the multipath topology. The output may contain
Copy link
Collaborator

@mwilck mwilck Jan 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please add that the same output can be obtained by using multipathd show topology. More often than not, this is more reliable than multipath -ll, because it reflects multipathd's internal state.

placeholder values when path information is unavailable:
.
.TP
.B ##,##
Displayed for vendor and product fields when a multipath device has no paths with valid
SCSI inquiry data. This typically occurs when all underlying path devices have been
removed from the system, but the multipath map could not be flushed (e.g., because it
was still in use). To resolve this situation, ensure no processes are using the device
and run \fImultipathd reconfigure\fR or \fImultipath -f <device>\fR to remove the stale map.
Copy link
Collaborator

@mwilck mwilck Jan 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This paragraph is too long and stands out too much. Please move this section below the explanation of the "healthy" output, refer to it, and add a "(##)" where you mention "placeholder values" above.

.
.TP
.B ##
Displayed for individual vendor, product, or revision fields of a path when that
specific SCSI inquiry data is unavailable.
.
.PP
Path checker states:
Copy link
Collaborator

@mwilck mwilck Jan 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Better: "Path state as determined by multipath's internal path checking algorithm".

.
.TP 12
.B up
Path is operational and can handle I/O.
.TP
.B down
Path is not operational.
.TP
.B ghost
Path is in standby mode (ALUA transitioning state).
Copy link
Collaborator

@mwilck mwilck Jan 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

STANDBY indicates the "passive" state in some active/passive arrays, this state can persist for extended periods of time. TRANSITIONING is different, it's a temporary state that won't persist for longer than the "transitioning timeout" advertized by the storage (typically 60s).

Also, ghost state is not exclusive to ALUA. It is also used by the RDAC checker, and for paths whose size couldn't be determined.

You don't have to explain all these details. Just don't confuse standby and transitioning.

.TP
.B shaky
Path is unreliable (intermittent failures).
Copy link
Collaborator

@mwilck mwilck Jan 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Refer to the multipath.conf man page here (section "Shaky paths detection").

.TP
.B pending
Path check is in progress.
.TP
.B timeout
Path check timed out.
.TP
.B removed
Path device has been removed from the system.
.TP
.B delayed
Path is delayed before being marked as up.
.
.PP
Device mapper path states:
Copy link
Collaborator

@mwilck mwilck Jan 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Better: "State of the path device in the device mapper table in the kernel".

.
.TP 12
.B active
Path is active in the device mapper table.
Copy link
Collaborator

@mwilck mwilck Jan 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe add: "Only active paths in the active path group can handle I/O".

.TP
.B failed
Path has been marked as failed by the device mapper.
.TP
.B undef
Path state is undefined (path not found in device mapper).
.
Copy link
Collaborator

@mwilck mwilck Jan 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While you're at it, you may also want to explain the kernel device state ("running" / "offline" / "unknown"). It corresponds to the state sysfs attribute of the SCSI/NVMe device. "offline" devices don't have a valid checker state most of the time, because they usually can't be reached by the checker, either.

.\" ----------------------------------------------------------------------------
.SH "EXAMPLES"
.\" ----------------------------------------------------------------------------
.
.SS Normal multipath topology output
.PP
.RS
.nf
mpatha (36001405e27f5cc80000900000490000) dm-0 LIO-ORG,lun0
size=1.0G features='0' hwhandler='1 alua' wp=rw
|-+- policy='service-time 0' prio=50 status=active
| `- 1:0:0:0 sda 8:0 active ready running
`-+- policy='service-time 0' prio=10 status=enabled
`- 2:0:0:0 sdb 8:16 active ready running
.fi
.RE
.PP
This shows a healthy multipath device with two active paths.
.
.SS Output with removed paths
.PP
.RS
.nf
mpathb (36001405e27f5cc80000900000fa0000) dm-1 ##,##
size=500G features='0' hwhandler='0' wp=rw
`-+- policy='service-time 0' prio=0 status=enabled
|- #:#:#:# - #:# failed undef
`- #:#:#:# - #:# failed undef
.fi
.RE
.PP
This indicates all path devices have been removed from the system, but the
multipath map could not be flushed because it was still in use.
The \fB##,##\fR placeholder appears instead of vendor and product information.
.PP
To resolve this, ensure no processes are using the device, then flush the map:
.RS
\fBmultipath -f mpathb\fR
.RE
or trigger a full reconfiguration:
.RS
\fBmultipathd reconfigure\fR
.RE
.
Copy link
Collaborator

@mwilck mwilck Jan 2, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a nice description of a common "failure" situation. But I am not sure if it belongs into the multipath(8) man page (the same content applies to multipathd show topology). I can't easily recommend a better place either, though. For now I guess it's ok to have it here. But please, as noted above, move the paragraph about the placeholders down to this section.

.\" ----------------------------------------------------------------------------
.SH "SEE ALSO"
.\" ----------------------------------------------------------------------------
.
Expand Down