Subject: [PATCH] [BZ 161888] lsluns: clarify discovery use case, relation to NPIV and to zfcp auto LUN scan From: Jens Remus 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: 0daa7ba0b558ff22fa1c1e014e754cbd08366c00 Problem-ID: 161888 Upstream-Description: lsluns: clarify discovery use case, relation to NPIV and to zfcp auto LUN scan Signed-off-by: Steffen Maier Reviewed-by: Jens Remus Signed-off-by: Michael Holzheu Signed-off-by: Jens Remus --- zconf/lsluns | 3 +++ zconf/lsluns.8 | 18 ++++++++++++++++++ 2 files changed, 21 insertions(+) --- a/zconf/lsluns +++ b/zconf/lsluns @@ -174,6 +174,9 @@ $PROGRAM_NAME [-c ] ... [-p ] ... [-p ] ... [-h] [-v] --- a/zconf/lsluns.8 +++ b/zconf/lsluns.8 @@ -46,6 +46,24 @@ encryption, use other tools such as or .BR "lsscsi \-tv" . +.SS Details on lsluns without -a option + +.TP +Prerequisite +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. + +With available and enabled zfcp automatic LUN scan, +the kernel already performs LUN discovery. + +.TP +Temporary LUN Attachment +If not attached already, lsluns temporarily attaches LUN 0 +(or if this fails the WLUN 0xc101000000000000) during runtime. +Do not terminate lsluns with a signal. Signals interfere +with the removal of temporarily attached LUNs. + .SH OPTIONS .TP .BR \-a ", " \-\-active