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@xxxxxxxxxx> Cc: Xose Vazquez Perez <xose.vazquez@xxxxxxxxx> Signed-off-by: Martin Wilck <mwilck@xxxxxxxx> --- 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 -- dm-devel mailing list dm-devel@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/dm-devel
