[dm-devel] [PATCH 66/78] Update multipath.conf.5 to clarify wwid generation

[Hannes Reinecke]

Add a new section in multipath.conf.5 to clarify wwid generation
and update wrong defaults for the property whitelist.

Signed-off-by: Hannes Reinecke <hare at suse.de>
---
 multipath.conf.defaults    |  2 +-
 multipath/multipath.conf.5 | 33 ++++++++++++++++++++++++++++-----
 2 files changed, 29 insertions(+), 6 deletions(-)

diff --git a/multipath.conf.defaults b/multipath.conf.defaults
index a12a4f4..a4e8f75 100644
--- a/multipath.conf.defaults
+++ b/multipath.conf.defaults
@@ -73,7 +73,7 @@
 #	}
 #}
 #blacklist_exceptions {
-#	property "(ID_SCSI_VPD|ID_WWN)"
+#	property "(SCSI_IDENT_.*|ID_WWN)"
 #}
 #devices {
 #	device {
diff --git a/multipath/multipath.conf.5 b/multipath/multipath.conf.5
index 7e17f62..6980010 100644
--- a/multipath/multipath.conf.5
+++ b/multipath/multipath.conf.5
@@ -55,9 +55,8 @@ section.
 .TP
 .B multipaths
 This section defines the multipath topologies. They are indexed by a
-\fIWorld Wide Identifier\fR(wwid), which is taken to be the value of
-the udev attribute given by the
-\fIuid_attribute\fR keyword.
+\fIWorld Wide Identifier\fR(wwid). For details on the wwid generation
+see section \fBWWID generation\fR below.
 .TP
 .B devices
 This section defines the device-specific settings.
@@ -176,7 +175,7 @@ identifier. Default value is
 .B getuid_callout
 The default program and args to callout to obtain a unique path
 identifier. Should be specified with an absolute path.
-This parameter is deprecated; \fIuid_attribute\fR should be used instead.
+This parameter is deprecated.
 .TP
 .B prio
 The name of the path priority routine. The specified routine
@@ -534,7 +533,7 @@ The \fIWorld Wide Identification\fR of a device.
 .TP
 .B property
 Regular expression of the udev property to be whitelisted. Defaults to
-.I (ID_WWN|ID_SCSI_VPD)
+.I (ID_WWN|SCSI_IDENT_.*)
 .TP
 .B devnode
 Regular expression of the device nodes to be whitelisted.
@@ -771,6 +770,30 @@ sections:
 .RE
 .PD
 .LP
+.SH "WWID generation"
+Multipath uses a \fIWorld Wide Identification\fR (wwid) to determine
+which paths belong to the same device. Each path presenting the same
+wwid is assumed to point to the same device.
+.LP
+The wwid is generated by three methods (in the order of preference):
+.TP 17
+.B getuid_callout
+Use the specified external program; cf \fIgetuid_callout\fR above.
+Care should be taken when using this method; the external program
+needs to be loaded from disk for execution, which might lead to
+deadlock situations in an all-paths-down scenario.
+.TP
+.B uid_attribute
+Use the value of the specified udev attribute; cf \fIuid_attribute\fR
+above. This method is preferred to \fIgetuid_callout\fR as multipath
+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.
 .SH "KNOWN ISSUES"
 The usage of
 .B queue_if_no_path
-- 
1.8.4.5