[dm-devel] [PATCH v2 30/30] multipath.conf.5: Improve documentation of WWID determination

[Martin Wilck]

Clarify the effect of setting uid_attrs, and document the effect of setting
uid_attribute to an empty string. Replace the arcane "vpd_pg83" with
something easier to understand. Tell the user that the defaults are
usually good enough.

Cc: Tang Junhui <tang.junhui at zte.com.cn>
Cc: Xose Vazquez Perez <xose.vazquez at gmail.com>
Signed-off-by: Martin Wilck <mwilck at suse.com>
---
 multipath/multipath.conf.5 | 48 ++++++++++++++++++++++++--------------
 1 file changed, 31 insertions(+), 17 deletions(-)

diff --git a/multipath/multipath.conf.5 b/multipath/multipath.conf.5
index d5fe38ac..f7d21b4c 100644
--- a/multipath/multipath.conf.5
+++ b/multipath/multipath.conf.5
@@ -241,23 +241,32 @@ The default is: \fBfailover\fR
 .
 .TP
 .B uid_attrs
-The udev attribute providing a unique path identifier for corresponding
-type of path devices. If this field is configured and matched with type
-of device, it would override any other methods providing for device
-unique identifier in config file, and it would activate merging uevents
-according to the identifier to promote effiecncy in processing uevents.
-It has no default value, if you want to identify path by udev attribute
-and to activate merging uevents for SCSI and DASD devices, you can set
-its value as: \fIuid_attrs "sd:ID_SERIAL dasd:ID_UID"\fR.
+.
+Setting this option activates \fBmerging uevents\fR by WWID, which may improve
+uevent processing effiency. Moreover, it's an alternative method to configure
+the udev properties to use for determining unique path identifiers (WWIDs).
 .RS
-.TP
-The default is: \fB<unset>\fR
+.PP
+The value of this option is a space separated list of records like
+\(dq\fItype:ATTR\fR\(dq, where \fItype\fR is matched against the beginning
+of the device node name (e.g. \fIsd:ATTR\fR matches \fIsda\fR), and
+\fIATTR\fR is the name of the udev property to use for matching devices.
+.PP
+If this option is configured and matches the device
+node name of a device, it overrides any other configured  methods for
+determining the WWID for this device.
+.PP
+The default is: \fB<unset>\fR. To enable uevent merging, set it e.g. to
+\(dqsd:ID_SERIAL dasd:ID_UID nvme:ID_WWN\(dq.
 .RE
 .
 .
 .TP
 .B uid_attribute
-The udev attribute providing a unique path identifier.
+The udev attribute providing a unique path identifier (WWID). If
+\fIuid_attribute\fR is set to the empty string, WWID determination is done
+using the \fIsysfs\fR method rather then using udev (not recommended in
+production; see \fBWWID generation\fR below).
 .RS
 .TP
 The default is: \fBID_SERIAL\fR, for SCSI devices
@@ -1635,8 +1644,8 @@ WWID is assumed to point to the same device.
 The WWID is generated by four methods (in the order of preference):
 .TP 17
 .B uid_attrs
-The WWID is derived from udev attributes by matching the device node name. See
-description of \fIuid_attrs\fR in the defaults section above.
+The WWID is derived from udev attributes by matching the device node name; cf
+\fIuid_attrs\fR above.
 .TP
 .B getuid_callout
 Use the specified external program; cf \fIgetuid_callout\fR above.
@@ -1651,10 +1660,15 @@ does not need to call any external programs here. However, under
 certain circumstances udev might not be able to generate the requested
 variable.
 .TP
-.B vpd_pg83
-If none of the \fIgetuid_callout\fR or \fIuid_attribute\fR parameters
-are present multipath will try to use the sysfs attribute
-\fIvpd_pg83\fR to generate the WWID.
+.B sysfs
+Try to determine the WWID from sysfs attributes.
+For SCSI devices, this means reading the Vital Product Data (VPD) page
+\(dqDevice Identification\(dq (0x83).
+.PP
+The default settings (using udev and \fBuid_attribute\fR configured from
+the built-in hardware table) should work fine
+in most scenarios. Users who want to enable uevent merging must set
+\fBuid_attrs\fR.
 .
 .
 .\" ----------------------------------------------------------------------------
-- 
2.21.0