s390-tools/s390-tools-sles15-lsluns-enhance-usage-statement-and-man-page.patch

Subject: [PATCH] [BZ 161888] lsluns: enhance usage statement and man page
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:  e748fff3479f8f4ae7e8262b4913f6d08ff78f66
Problem-ID:   161888

Upstream-Description:

              lsluns: enhance usage statement and man page

              The wording in the lsluns usage statement and man page was misleading
              in several aspects:

              * lsluns does not list all LUNs, just those discovered in the FC SAN
              * lsluns -a should only be used to display the LUN encryption status

              Fix filter option arguments. Clarify filter option usage. Refer to
              lszfcp and lsscsi.

              Reported-by: Steffen Maier <maier@linux.vnet.ibm.com>
              Signed-off-by: Jens Remus <jremus@linux.vnet.ibm.com>
              Reviewed-by: Steffen Maier <maier@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   |   45 +++++++++++++++------------
 zconf/lsluns.8 |   93 +++++++++++++++++++++++++++++++++++++++------------------
 2 files changed, 91 insertions(+), 47 deletions(-)

--- a/zconf/lsluns
+++ b/zconf/lsluns
@@ -1,6 +1,6 @@
 #!/usr/bin/perl
 #
-# lsluns - Tool to list all available LUNs
+# lsluns - list LUNs discovered in the FC SAN, or show encryption state of attached LUNs
 #
 # Copyright IBM Corp. 2008, 2017
 #
@@ -169,32 +169,39 @@ sub get_lun_hash
 
 sub lsluns_usage {
     print <<EOD;
-Usage: $PROGRAM_NAME [<options>]
+Usage:
+$PROGRAM_NAME [-c <busid>] ... [-p <wwpn>] ... [-h] [-v]
 
-    lsluns provides information for LUNs.
+    List LUNs discovered in the Fibre Channel (FC) Storage Area Network (SAN).
+    This causes extra SAN traffic for each target port WWPN.
 
-    The default is to list all LUNs that are available via the attached ports.
-    The display can be limited by specifying an adapter or a port.
+$PROGRAM_NAME -a [-c <busid>] ... [-p <wwpn>] ... [-h] [-v]
+
+    Show encryption state of the attached LUNs.
+    This causes extra SAN traffic for each attached LUN.
+
+For all other uses, such as listing attached LUNs or properties other than
+encryption, use other tools such as "lszfcp -D" or "lsscsi -tv".
+
+Limit the listing by specifying one or more adapters (FCP device
+bus-IDs) or target port WWPNs or both.
 
 Options:
-    -a, --active
-    Shows all activated LUNs.
-    In addition LUN encryption information is provided.
-    e.g. "lsluns -a"
-
-    -c, --ccw
-    Shows LUNs for a specific ccw device.
-    e.g. "lsluns -c 0.0.3922"
-
-    -p, --port
-    Shows LUNs for a specific port.
-    e.g. "lsluns -p 0x5005123456789000"
+    -c <busid>, --ccw <busid>
+        Filter LUNs by adapter with the specified FCP device bus-ID. Can be
+        specified multiple times.
+        For example: "$PROGRAM_NAME -c 0.0.3922"
+
+    -p <wwpn>, --port <wwpn>
+        Filter LUNs by target port with the specified WWPN. Can be specified
+        multiple times.
+        For example: "$PROGRAM_NAME -p 0x5005123456789000"
 
     -h, --help
-    Print help message and exit.
+        Print help message and exit.
 
     -v, --version
-    Display version info and exit.
+        Display version information and exit.
 EOD
     exit 0;
 }
--- a/zconf/lsluns.8
+++ b/zconf/lsluns.8
@@ -2,61 +2,93 @@
 .\" s390-tools is free software; you can redistribute it and/or modify
 .\" it under the terms of the MIT license. See LICENSE for details.
 .\"
-.TH LSLUNS 8 "June 2008" "s390-tools"
+.TH LSLUNS 8 "2017-02-17" "s390-tools"
 .SH NAME
-lsluns \- list available LUNs
+lsluns \- list LUNs discovered in the FC SAN, or show encryption state of
+attached LUNs
 
 .SH SYNOPSIS
 .B lsluns
+.RB [\| \-c
+.IR busid \|]\ .\|.\|.
+.RB [\| \-p
+.IR wwpn \|]\ .\|.\|.
+.\" --active
+.br
+.B lsluns \-a
+.RB [\| \-c
+.IR busid \|]\ .\|.\|.
+.RB [\| \-p
+.IR wwpn \|]\ .\|.\|.
+.\" --help and --version
+.br
+.B lsluns
 .RB [\| \-h \|]
 .RB [\| \-v \|]
-.RB [\| \-c
-.IR adapter\ id:0.0.XXXX \|]\ .\|.\|.
-.RB [ \-p
-.IR port\ number:0xXXXXXXXXXXXXXXXX \|]\ .\|.\|.
 
 .SH DESCRIPTION
 .PP
 .B lsluns
-does a listing of all available LUNs.
-
-The default is to list all LUNs that are found. The listing can be
-limited by specifying an adapter or a port.
+lists all logical unit numbers (LUNs) discovered in the
+Fibre Channel (FC) Storage Area Network (SAN).
+This causes extra SAN traffic for each target port WWPN.
+
+.B lsluns -a
+shows the encryption state of the attached LUNs.
+This causes extra SAN traffic for each attached LUN.
+
+Limit the listing by specifying one or more adapters (FCP device
+bus-IDs) or target port WWPNs or both.
+
+For all other uses, such as listing attached LUNs or properties other than
+encryption, use other tools such as
+.B lszfcp \-D
+or
+.BR "lsscsi \-tv" .
 
 .SH OPTIONS
 .TP
+.BR \-a ", " \-\-active
+Show the encryption state of the attached LUNs. Encrypted devices are indicated
+with a bracketed X immediately following the LUN number.
+.TP
+.BI \-c\  busid \fR,\ \fB\-\-ccw= busid
+Filter LUNs by adapter with the specified FCP device bus-ID. This option can be
+specified multiple times. When used in conjunction with \fB\-p\fR, only those
+LUNs are listed that also satisfy at least one of the \fB\-p\fR constraints.
+.TP
+.BI \-p\  wwpn \fR,\ \fB\-\-port= wwpn
+Filter LUNs by target port with the specified WWPN. This option can be
+specified multiple times. When used in conjunction with \fB\-c\fR, only those
+LUNs are listed that also satisfy at least one of the \fB\-c\fR constraints.
+.TP
 .BR \-h ", " \-\-help
 Print help message and exit.
 .TP
 .BR \-v ", " \-\-version
-Display version info and exit.
-.TP
-.BI \-c\  adapter \fR,\ \fB\-\-ccw= adapter
-Shows LUNs for a specific adapter.
-.TP
-.BI \-p\  port \fR,\ \fB\-\-port= port
-Shows LUNs for a specific port.
-.TP
-.BR \-a ", " \-\-active
-Shows all activated LUNs. In addition information is provided
-whether the LUN is encrypted or not. This is indicated with a bracketed X 
-right after the LUN number.
+Display version information and exit.
 
 .SH EXAMPLES
 .TP
 .B "lsluns"
 .RS
-Shows all available LUNs.
+Lists all LUNs discovered in the FC SAN.
 .RE
 .TP
 .BI "lsluns \-c " 0.0.3922
-Shows all LUNs found on adapter \fI0.0.3922\fR.
+Lists all LUNs discovered in the FC SAN on adapter \fI0.0.3922\fR.
 .TP
 .BI "lsluns \-p " 0x5005123456789000
-Shows all LUNs for port \fI0x5005123456789000\fR.
+Lists all LUNs discovered in the FC SAN on target port
+\fI0x5005123456789000\fR.
 .TP
-.BI "lsluns \-c " 0.0.3922 " \-p " 0x5005123456789000
-Shows all LUNs for adapter \fI0.0.3922\fR and port \fI0x5005123456789000\fR.
+.BI "lsluns \-c " 0.0.3922 " \-c " 0.0.fc00 \
+" \-p " 0x5005123456789000 " \-p " 0x5005abcdefabc000
+Lists all LUNs discovered in the FC SAN on:
+adpater \fI0.0.3922\fR and port \fI0x5005123456789000\fR,
+adapter \fI0.0.3922\fR and port \fI0x5005abcdefabc000\fR,
+adapter \fI0.0.fc00\fR and port \fI0x5005123456789000\fR, or
+adapter \fI0.0.fc00\fR and port \fI0x5005abcdefabc000\fR.
 .TP
 .B "lsluns -a"
 adapter = 0.0.3c02
@@ -64,4 +96,9 @@ adapter = 0.0.3c02
                 lun = 0x401040a200000000(X)     /dev/sg0        Disk    IBM:2107900
                 lun = 0x401040a300000000        /dev/sg1        Disk    IBM:2107900
 
-Shows all active LUNs including the information whether the device is encrypted or not.
+Shows the encryption status of attached LUNs. A bracketed X suffixed to a LUN
+indicates that the device is encrypted.
+
+.SH "SEE ALSO"
+.BR lszfcp (8),
+.BR lsscsi (8)