| Message ID | 20240513173646.94424-8-bmarzins@redhat.com (mailing list archive) |
|---|---|
| State | Not Applicable, archived |
| Delegated to: | christophe varoqui |
| Headers | show |
| Series | multipath-tools man pages: add missing information | expand |
On Mon, May 13, 2024 at 01:36:46PM -0400, Benjamin Marzinski wrote: > Suggested-by: Nitin Yewale <nyewale@redhat.com> > Signed-off-by: Benjamin Marzinski <bmarzins@redhat.com> Oops. I forgot to update the man page date. Martin, either I can send a new patch or you can feel free to update the date when you apply this one, whichever you'd prefer. -Ben > --- > 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 > +.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. > +.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 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. > +.TP > +.B %S > +The device size. > +.TP > +.B %f > +The device table features string. > +.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. > +.TP > +.B %g > +Data from vendor specific vpd pages for the device, if any. > +.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 > +.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. > +.TP > +.B %T > +The multipathd path checker state of the device. > +.TP > +.B %s > +The vendor/product/revision string for the device. > +.TP > +.B %c > +The device's path checker name. > +.TP > +.B %C > +The progress towards the next path checker run on the device. > +.TP > +.B %p > +The device priority. > +.TP > +.B %S > +The device size. > +.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. > +.TP > +.B %n > +The target World Wide Node Name (WWNN) of the device. > +.TP > +.B %R > +The host World Wide Port Name (WWPN) of the device. > +.TP > +.B %r > +The target World Wide Port Name (WWPN) of the device. > +.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. > +.TP > +.B %g > +Data from vendor specific vpd pages for the device, if any. > +.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. > +.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 > +.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" > .\" ---------------------------------------------------------------------------- > . > -- > 2.45.0 >
On Mon, 2024-05-13 at 13:36 -0400, Benjamin Marzinski wrote: > Suggested-by: Nitin Yewale <nyewale@redhat.com> > Signed-off-by: Benjamin Marzinski <bmarzins@redhat.com> 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" > .\" ---------------------------------------------------------------- > ------------ > .
On Mon, 2024-05-13 at 15:11 -0400, Benjamin Marzinski wrote: > On Mon, May 13, 2024 at 01:36:46PM -0400, Benjamin Marzinski wrote: > > Suggested-by: Nitin Yewale <nyewale@redhat.com> > > Signed-off-by: Benjamin Marzinski <bmarzins@redhat.com> > > Oops. I forgot to update the man page date. Martin, either I can send > a > new patch or you can feel free to update the date when you apply this > one, whichever you'd prefer. No problem, I can do this. Would you like to have this included in the 0.9.9 release? As all these changes are small and non-controversial, I tend to include them, unless Christophe merges 0.9.9 very quickly. Martin
On Fri, May 24, 2024 at 04:29:22PM +0200, Martin Wilck wrote: > On Mon, 2024-05-13 at 15:11 -0400, Benjamin Marzinski wrote: > > On Mon, May 13, 2024 at 01:36:46PM -0400, Benjamin Marzinski wrote: > > > Suggested-by: Nitin Yewale <nyewale@redhat.com> > > > Signed-off-by: Benjamin Marzinski <bmarzins@redhat.com> > > > > Oops. I forgot to update the man page date. Martin, either I can send > > a > > new patch or you can feel free to update the date when you apply this > > one, whichever you'd prefer. > > No problem, I can do this. > Would you like to have this included in the 0.9.9 release? > As all these changes are small and non-controversial, I tend to include > them, unless Christophe merges 0.9.9 very quickly. Sure, and I can update the date when I send a V2 set with your suggestions. > > Martin
On Fri, May 24, 2024 at 04:27:12PM +0200, Martin Wilck wrote: > On Mon, 2024-05-13 at 13:36 -0400, Benjamin Marzinski wrote: > > Suggested-by: Nitin Yewale <nyewale@redhat.com> > > Signed-off-by: Benjamin Marzinski <bmarzins@redhat.com> > > Thanks. This is useful, but I have a few additional suggestions below. They seem reasonable. I'll update this. -Ben > > 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" > > .\" ---------------------------------------------------------------- > > ------------ > > .
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 +.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. +.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 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. +.TP +.B %S +The device size. +.TP +.B %f +The device table features string. +.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. +.TP +.B %g +Data from vendor specific vpd pages for the device, if any. +.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 +.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. +.TP +.B %T +The multipathd path checker state of the device. +.TP +.B %s +The vendor/product/revision string for the device. +.TP +.B %c +The device's path checker name. +.TP +.B %C +The progress towards the next path checker run on the device. +.TP +.B %p +The device priority. +.TP +.B %S +The device size. +.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. +.TP +.B %n +The target World Wide Node Name (WWNN) of the device. +.TP +.B %R +The host World Wide Port Name (WWPN) of the device. +.TP +.B %r +The target World Wide Port Name (WWPN) of the device. +.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. +.TP +.B %g +Data from vendor specific vpd pages for the device, if any. +.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. +.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 +.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" .\" ---------------------------------------------------------------------------- .
Suggested-by: Nitin Yewale <nyewale@redhat.com> Signed-off-by: Benjamin Marzinski <bmarzins@redhat.com> --- multipathd/multipathd.8.in | 211 ++++++++++++++++++++++++++++++++++++- 1 file changed, 207 insertions(+), 4 deletions(-)