multipath.8: document output format for -l/-ll options #131
Conversation
This comment has been minimized.
This comment has been minimized.
Add OUTPUT FORMAT section to man page explaining: - ##,## and ## placeholders for missing device info - Path checker states (up, down, ghost, shaky, pending, timeout, removed, delayed) - Device mapper states (active, failed, undef) Add EXAMPLES section showing: - Normal healthy multipath topology output - Output with removed paths (##,## placeholders) - Commands to resolve stale multipath maps Update spelling dictionary with new terms used in examples. This helps users understand the meaning of placeholder values that appear when path devices have been removed from the system but the multipath map could not be flushed. Fixes: opensvc#12
anatoliiohorodnyk
force-pushed
the
docs-output-format
branch
from
e747b0c to
d180a12
Compare
There was a problem hiding this comment.
Thanks a lot for your contribution! I have put a few comments here.
Please note that multipath-tools still uses a mailing-list based develoment model (see the "Contributing" section in the README).
In the commit message, you are pretty much stating the obvious, so you could shorten the message somewhat. But please add a Signed-off-by: trailer when you submit to the dm-devel mailing list.
| Path is not operational. | ||
| .TP | ||
| .B ghost | ||
| Path is in standby mode (ALUA transitioning state). |
There was a problem hiding this comment.
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.
| 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. |
There was a problem hiding this comment.
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.
| Path is in standby mode (ALUA transitioning state). | ||
| .TP | ||
| .B shaky | ||
| Path is unreliable (intermittent failures). |
There was a problem hiding this comment.
Refer to the multipath.conf man page here (section "Shaky paths detection").
| specific SCSI inquiry data is unavailable. | ||
| . | ||
| .PP | ||
| Path checker states: |
There was a problem hiding this comment.
Better: "Path state as determined by multipath's internal path checking algorithm".
| .SH "OUTPUT FORMAT" | ||
| .\" ---------------------------------------------------------------------------- | ||
| . | ||
| The \fB-l\fR and \fB-ll\fR options display the multipath topology. The output may contain |
There was a problem hiding this comment.
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.
| Path is delayed before being marked as up. | ||
| . | ||
| .PP | ||
| Device mapper path states: |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
Maybe add: "Only active paths in the active path group can handle I/O".
| .TP | ||
| .B undef | ||
| Path state is undefined (path not found in device mapper). | ||
| . |
There was a problem hiding this comment.
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.
| .RS | ||
| \fBmultipathd reconfigure\fR | ||
| .RE | ||
| . |
There was a problem hiding this comment.
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.
| linux | ||
| LIO | ||
| lpthread | ||
| lun |
There was a problem hiding this comment.
Just replace "Lun" with "lun". Or better even, use "LUN" in your text. After all, it's an acronym for "Logical Unit Number".
2 participants
Add OUTPUT FORMAT section to man page explaining:
Add EXAMPLES section showing:
This helps users understand the meaning of placeholder values that appear when path devices have been removed from the system but the multipath map could not be flushed.
Fixes: #12