On Mon, 2024-05-13 at 13:36 -0400, Benjamin Marzinski wrote:
> Suggested-by: Nitin Yewale <nyewale@xxxxxxxxxx>
> Signed-off-by: Benjamin Marzinski <bmarzins@xxxxxxxxxx>
Thanks. This is useful, but I have a few additional suggestions below.
Martin
> ---
> multipathd/multipathd.8.in | 211
> ++++++++++++++++++++++++++++++++++++-
> 1 file changed, 207 insertions(+), 4 deletions(-)
>
> diff --git a/multipathd/multipathd.8.in b/multipathd/multipathd.8.in
> index 32976052..ff150f3d 100644
> --- a/multipathd/multipathd.8.in
> +++ b/multipathd/multipathd.8.in
> @@ -117,7 +117,7 @@ Show the paths that multipathd is monitoring, and
> their state.
> .B list|show paths [raw] format $format
> Show the paths that multipathd is monitoring, using a format string
> with path
> format wildcards. Adding \fIraw\fR will remove the headers and
> alignment
> -padding from the ouput.
> +padding from the output. See "Path format wildcards" below.
> .
> .TP
> .B list|show path $path
> @@ -131,7 +131,8 @@ Show the multipath devices that the multipathd is
> monitoring.
> .B list|show maps|multipaths [raw] format $format
> Show the status of all multipath devices that the multipathd is
> monitoring,
> using a format string with multipath format wildcards. Adding
> \fIraw\fR will
> -remove the headers and alignment padding from the output.
> +remove the headers and alignment padding from the output. See
> "Multipath
> +format wildcards" below.
> .
> .TP
> .B list|show maps|multipaths status
> @@ -162,7 +163,7 @@ Show topology of a single multipath device
> specified by $map, for example
> .B list|show map|multipath $map [raw] format $format.
> Show the status of multipath device $map, using a format string with
> multipath
> format wildcards. Adding \fIraw\fR will remove the headers and
> alignment
> -padding from the output.
> +padding from the output. See "Multipath format wildcards" below.
> .
> .TP
> .B list|show map|multipath $map json
> @@ -170,7 +171,8 @@ Show information about multipath device $map in
> JSON format.
> .
> .TP
> .B list|show wildcards
> -Show the format wildcards used in interactive commands taking
> $format.
> +Show the format wildcards used in interactive commands taking
> $format. See
> +"Format Wildcards" below.
> .
> .TP
> .B list|show config
> @@ -367,6 +369,207 @@ Stop multipathd.
> .
> .
> .\" ----------------------------------------------------------------
> ------------
> +.SH "Format Wildcards"
> +.\" ----------------------------------------------------------------
> ------------
> +.
> +Multipathd commands that take a $format option require a format
> string. This
> +string controls how a device is printed and should include format
> wildcards.
> +When the devices are printed, these wildcards will be replaced by
> the
> +appropriate device information. The following wildcards are
> supported.
> +.TP
> +.B Multipath format wildcards
> +.RS
> +.TP 12
I can see that you're using the same ordering as in print.c. Perhaps we
should use alphabetical ordering in the man page? Or do you think it
makes more sense to group the wildcards semantically?
Alternatively,
> +.B %n
> +The device name.
> +.TP
> +.B %w
> +The device WWID (uuid).
> +.TP
> +.B %d
> +The device sysfs name (dm-<minor_nr>).
> +.TP
> +.B %F
> +The device \fBfailback\fR setting. For deferred failbacks, it will
> either
> +print the configured time if a deferred failback is not in progress,
> or
> +it will show the current progress of a deferred failback.
If you agree to amend 3/7, please don't forget to change this, too.
> +.TP
> +.B %Q
> +The device \fBno_path_retry\fR setting. If no_path_retry is set to a
> +number of retires, it will either print the configured number of
^ typo
> checker
> +retries if the device is not in recovery mode, the number of seconds
> until
> +queueing is disabled if the device is queueing in recovery mode, or
> \fIoff\fR
> +if the device has disabled queueing.
> +.TP
> +.B %N
> +The number of active paths for the device.
> +.TP
> +.B %r
> +The device write-protect setting, either \fIro\fR or \fIrw\fR.
> +.TP
> +.B %t
> +The device-mapper state of the device, either \fIsuspend\fR or
> \fIactive\fR.
"suspend" has been chosen to avoid field overflow, but it sounds
weird.
\fIsuspend\fR if the device is suspended, and \fIactive\fR otherwise ?
> +.TP
> +.B %S
> +The device size.
Explain our "K", "M", "G", "T", "P" suffixes here?
> +.TP
> +.B %f
> +The device table features string.
Suggestion: 'The "features" string of the device-mapper table in the
kernel.'
> +.TP
> +.B %x
> +The number of times the device has entered a state where it will
> fail IO.
> +This is an alias for the \fB%4\fR wildcard.
> +This value can be reset with the '\fIreset map $map stats\fR'
> command.
> +.TP
> +.B %h
> +The device table hardware handler string.
> +.TP
> +.B %A
> +The last action multipathd took on the device. This wildcard is for
> debugging
> +use, as understanding its meaning requires looking at the code.
> +.TP
> +.B %0
> +The number of times a path in the device has failed.
> +This value can be reset with the '\fIreset map $map stats\fR'
> command.
> +.TP
> +.B %1
> +The number of times multipathd has initiated a pathgroup switch for
> the device.
> +This value can be reset with the '\fIreset map $map stats\fR'
> command.
> +.TP
> +.B %2
> +The number of times multipathd has loaded a new table for the
> device.
> +This value can be reset with the '\fIreset map $map stats\fR'
> command.
> +.TP
> +.B %3
> +The approximate number of seconds that multipathd has spent queueing
> with
> +no usable paths. This value can be reset with the '\fIreset map $map
> stats\fR'
> +command.
> +.TP
> +.B %4
> +The number of times the device has entered a state where it will
> fail IO.
> +This is an alias for the \fB%x\fR wildcard.
> +This value can be reset with the '\fIreset map $map stats\fR'
> command.
> +.TP
> +.B %s
> +The vendor/product string for the device.
> +.TP
> +.B %v
> +The array vendor string for the device.
> +.TP
> +.B %p
> +The array product string for the device.
> +.TP
> +.B %e
> +The array firmware revision string for the device.
> +.TP
> +.B %G
> +The foreign library used for the device, or \fB--\fR for native
> device-mapper
> +multipath devices.
Cross-ref to multipath.conf(5) here for an explanation of "foreign"?
> +.TP
> +.B %g
> +Data from vendor specific vpd pages for the device, if any.
"Currently multipathd supports VPD page 0xc0 für HPE 3PAR / Primera /
Alletra storage arrays."
> +.TP
> +.B %k
> +The actual max_sectors_kb setting for the device (which may be
> different from
> +the configured one).
> +.RE
> +.
> +.
> +.TP
> +.B Path format wildcards
> +.RS
> +.TP 12
> +.B %w
> +The device WWID (uuid).
> +.TP
> +.B %i
> +The device Host:Channel:Id:Lun
"for SCSI devices" (maybe explain what the data means for NVMe).
> +.TP
> +.B %d
> +The device sysfs name.
> +.TP
> +.B %D
> +The device major:minor
> +.TP
> +.B %t
> +The device-mapper state of the device, either \fIactive\fR or
> \fIfailed\fR.
> +.TP
> +.B %o
> +Whether the device is \fIoffline\fR or \fIrunning\fR.
'This shows "offline" if the device's "state" attribute in sysfs
is "offline" (for SCSI) or "dead" (for NMVe). For all other sysfs
states, it shows "running".'
> +.TP
> +.B %T
> +The multipathd path checker state of the device.
Should we list or explain the different states here?
> +.TP
> +.B %s
> +The vendor/product/revision string for the device.
> +.TP
> +.B %c
> +The device's path checker name.
"The name of the device's path checking algorithm"?
> +.TP
> +.B %C
> +The progress towards the next path checker run on the device.
'... in seconds'
> +.TP
> +.B %p
> +The device priority.
> +.TP
> +.B %S
> +The device size.
Format? See above
> +.TP
> +.B %z
> +The device serial number.
> +.TP
> +.B %M
> +The device marginal state, either \fImarginal\fR or \fInormal\fR.
> +.TP
> +.B %m
> +The multipath device that this device is a path of.
> +.TP
> +.B %N
> +The host World Wide Node Name (WWNN) of the device.
... if any
> +.TP
> +.B %n
> +The target World Wide Node Name (WWNN) of the device.
... if any
> +.TP
> +.B %R
> +The host World Wide Port Name (WWPN) of the device.
... if any
> +.TP
> +.B %r
> +The target World Wide Port Name (WWPN) of the device.
... if any
> +.TP
> +.B %a
> +The host adapter name for the device (only SCSI devices).
> +.TP
> +.B %G
> +The foreign library used for the device, or \fB--\fR for paths of
> native
> +device-mapper multipath devices.
See above
> +.TP
> +.B %g
> +Data from vendor specific vpd pages for the device, if any.
See above
> +.TP
> +.B %0
> +The number of times this device has failed.
> +.TP
> +.B %P
> +The device protocol. This output can be used for \fIprotocol\fR
> blacklist
> +entries.
I wouldn't mention the blacklist here. Rather, add a cross-ref to
multipath.conf(5).
> +.TP
> +.B %I
> +The device initialization state. Devices that have been fully
> initialized
> +are shown as \fIok\fR.
> +.TP
> +.B %L
> +The device SCSI LUN ID in hexadecimal format
'This is only meaningful for SCSI devices' ?
> +.TP
> +.B %A
> +The ALUA Target Port Group ID for the device, if applicable.
> +.TP
> +.B %k
> +The actual max_sectors_kb setting for the device (which may be
> different than
> +the configured one).
> +.RE
> +.
> +.
> +.\" ----------------------------------------------------------------
> ------------
> .SH "SYSTEMD INTEGRATION"
> .\" ----------------------------------------------------------------
> ------------
> .
