Subject: [PATCH] [BZ 161888] lsluns: point out IBM Storwize configuration requirements
From: Jens Remus <jremus@linux.vnet.ibm.com>

Description:  lsluns: Fix filter handling and documentation enhancements.
Symptom:      lsluns lists all LUNs discovered in the FC SAN despite user
              given filter(s) that do not match anything:
                # lsluns -c 0.0.5080
                    No valid combination found for adapter '0.0.5080'. Removing
                    from resource list.
                No valid parameters left, using all available resources in
                system.
                Scanning for LUNs on adapter 0.0.5090
                ...

              lsluns prints the message "No valid combination found for
              {adapter|port} '...'. Removing from resource list." for every
              adapter and port filter that does not contribute to the final
              filtered results.

              The formatting of the lsluns (8) man page is flawed.

              lsluns is used in unexpected or even unsupported ways.
Problem:      Scanning can be resource consumptive. So if a user already wants
              to filter, possibly to reduce resource consumption, he does not
              want to happen to scan everything and thus consume the worst case
              of resources.

              The message "No valid combination found for {adapter|port} '...'.
              Removing from resource list." is potentially confusing. It is
              unclear which combination is being referred to, especially if
              only one single adapter or port filter was specified. There is
              also no differentiation whether the denoted adapter or port
              exists for its own or not. It just does not exist in the final
              filtered results.

              The formatting of the lsluns (8) man page is flawed.

              The lsluns usage text and lsluns (8) man page lack the
              information on the intended use cases, requirements, and
              restrictions.
Solution:     Print a message and exit when all filters match nothing.

              Do not print confusing messages when a filter matches nothing.

              Fix man page formatting.

              Enhance usage text and man page. Clarify discovery use case,
              relation to NPIV and to zfcp auto LUN scan. Point out
              IBM Storwize configuration requirements. Document restriction to
              zfcp-only systems.
Reproduction: Use lsluns and specify adapter bus-ID and/or target port WWPN
              filter(s) that do not match anything. Either specify inexistent
              bus-IDs and/or WWPNs or invalid filter arguments.
Upstream-ID:  5f768dd52d87efddbd7efa23d57c6da62281728b
Problem-ID:   161888

Upstream-Description:

              lsluns: point out IBM Storwize configuration requirements

              Signed-off-by: Steffen Maier <maier@linux.vnet.ibm.com>
              Reviewed-by: Jens Remus <jremus@linux.vnet.ibm.com>
              Signed-off-by: Michael Holzheu <holzheu@linux.vnet.ibm.com>


Signed-off-by: Jens Remus <jremus@linux.vnet.ibm.com>
---
 zconf/lsluns   |    4 ++++
 zconf/lsluns.8 |   12 ++++++++++++
 2 files changed, 16 insertions(+)

--- a/zconf/lsluns
+++ b/zconf/lsluns
@@ -177,6 +177,10 @@ $PROGRAM_NAME [-c <busid>] ... [-p <wwpn
       Discovering LUNs only makes sense for NPIV-enabled FCP devices
     without zfcp automatic LUN scan. zfcp automatic LUN scan is available
     as of kernel version 2.6.37, if not disabled with zfcp.allow_lun_scan=0.
+      For storage products that do not support a REPORT LUNS
+    well-known logical unit (such as IBM Storwize products),
+    ensure that LUN 0 represents a valid peripheral device type.
+    See the man page for more information.
 
 $PROGRAM_NAME -a [-c <busid>] ... [-p <wwpn>] ... [-h] [-v]
 
--- a/zconf/lsluns.8
+++ b/zconf/lsluns.8
@@ -64,6 +64,18 @@ If not attached already, lsluns temporar
 Do not terminate lsluns with a signal. Signals interfere
 with the removal of temporarily attached LUNs.
 
+.TP
+Storage Products
+Some storage products return a peripheral device type of 31==0x1f
+with peripheral qualifier 0 in a SCSI standard INQUIRY command
+for an unmapped FCP LUN 0. Examples are: IBM Storwize products,
+including IBM V7000, IBM V840, IBM V9000, and IBM SAN Volume Controller.
+For lsluns to work with such storage products,
+you must have a host mapping on the storage, which maps some volume
+to exported FCP LUN 0x0000000000000000 (Storwize host map property "SCSI ID" 0)
+for each used FCP-device initiator WWPN. The volume can be
+a minimum-sized thin-provisioned shared stand-in volume.
+
 .SH OPTIONS
 .TP
 .BR \-a ", " \-\-active