File s390-tools-sles15-7-lstape-fix-SCSI-output-desc... of Package s390-tools

Overview Repositories Revisions Requests Users Attributes Meta

File s390-tools-sles15-7-lstape-fix-SCSI-output-description-in-man-page.patch of Package s390-tools (Revision 3a9a54f064c095256124a36daad05854)

Currently displaying revision 3a9a54f064c095256124a36daad05854 , Show latest

Subject: lstape, lsluns: handle non-zfcp; lin_tape multiple paths
From: Steffen Maier <maier@linux.ibm.com>

Description:  lstape, lsluns: handle non-zfcp; lin_tape multiple paths

Symptom:      lstape shows unexpected additional Device suffix numbers in
              excess output columns for each additional path of the same
              tape/changer driven by the IBM lin_tape device driver
              (independent of actual path failover enablement in lin_tape).
              It also shows a wrong number of found devices in the header
              (without --scsi-only).

lstape prints error about "Unexpected extra argument:" and the
              usage for "sg_inq" along with wrong tabular output.

lsluns prints ENOENT error text for "cat" on SCSI device sysfs
              attributes hba_id, wwpn, and fcp_lun.

lstape with --verbose option prints ENOENT error text for
              "cat" on SCSI device sysfs attributes hba_id and wwpn.

lstape man page: Description of --type and <devbusid> filter
              for channel tapes is incomplete. SCSI output description is
              incomplete.

lstape shows "N/A" instead of the HBA device bus-ID with
              virtio-scsi-ccw.

Problem:      s390-tools-1.8.0 before the first upstream commit b627b8d8e1ab
              ("Initial s390-tools-2.0.0 import") introduced SCSI
              tape/changer output for lstape. It used the SCSI device serial
              number as lookup key to find a match in IBM lin_tape device
              driver proc-fs output for a given SCSI device name. Multiple
              paths to the same tape/changer have the same serial number.
              Multiple matches cause excess arguments to printf. Explaining
              the resulting output, the bash man page says: "The format is
              reused as necessary to consume all of the arguments." This
              also causes a wrong number of found devices.

The default bash settings have nullglob disabled so if
              $SCSI_DEV/scsi_generic* aka
              /sys/bus/scsi/devices/*:*:*:*/scsi_generic* does not match
              anything, it leaves the glob pattern unmodified and
              SG_DEV=$(basename $SG_DEV/*) results in the literal "*". If
              $SG_INQ exists, it invoked sg_inq with more than the one
              allowed positional argument for a SCSI generic device node
              "sg_inq /dev/*". Causing error messages and the usage of
              sg_inq to land in $TAPE_SERIAL.

lsluns iterates SCSI generic devices and unconditionally
              reads zfcp-specific SCSI device sysfs attributes hba_id, wwpn,
              and fcp_lun.

lstape --verbose unconditionally reads zfcp-specific SCSI
              device sysfs attributes hba_id and wwpn.

<devbusid> filter missing from synopsis. <device-type> example
              at wrong place with <devbusid> filter. <devbusid> filter
              option description is a duplicate of <device-type> filter
              option description. SCSI output description misses fields.

Lstape only used the zfcp-specific sysfs attribute hba_id.

Solution:     Prefer sysfs to find lin_tape device name for SCSI device.
              Fallback: The lin_tape proc-fs output format has changed over
              the years. The HBA device driver string can contain whitespace
              (e.g. "Virtio SCSI HBA") and breaks the field numbers with
              tokenized parsing. Grep for the SCSI device name as word (to
              skip names with same substring, such as 0:0:1:1 also matching
              0:0:1:10) and cut the first field 'Number' (lin_tape device
              name suffix). If there is no SCSI column at all [lin_tape
              before v2.2.0] (and no SCSI LLDD or other column with a name
              accidentally matching an existing SCSI device name), we get no
              match and better bail out with the initialized "N/A" for the
              lstape column "Device".

To not have to rely on the nullglob setting, explicitly check
              for the existence of $SCSI_DEV/scsi_generic before evaluating
              SG_DEV=$(basename $SG_DEV/*). Also handle availability of
              sg_inq but absence of scsi_generic individually to provide the
              user with a hint if only sg is missing.

Simply skip non-zfcp SCSI devices, such as iSCSI or
              virtio-scsi-ccw, to not erroneously access absent attributes.

Assume "N/A" for HBA and WWPN of non-zfcp SCSI devices, such
              as iSCSI or virtio-scsi-ccw, to not erroneously access absent
              zfcp-specific sysfs attributes.

Add <devbusid> filter to synopsis. Move <device-type> example
              to <device-type> option. Replace <devbusid> filter option
              description. Move existing SCSI output description to a new
              subsection and add description of missing fields.

Also search sysfs for an ancestor with subsystem ccw.

Reproduction: Attach more than one path to the same SCSI tape or changer and
              load the IBM lin_tape device driver.

Unload sg kernel module.

Attach non-zfcp SCSI devices such as iSCSI or virtio-scsi-ccw.

man lstape

Attach SCSI tape or changer with virtio-scsi-ccw to a KVM
              guest and run "lstape --verbose".

Upstream-ID:  -
Problem-ID:   170633

Signed-off-by: Steffen Maier <maier@linux.ibm.com>
---
 zconf/lstape.8 |   68 +++++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 54 insertions(+), 14 deletions(-)

--- a/zconf/lstape.8
+++ b/zconf/lstape.8
@@ -29,20 +29,6 @@ channel attached tape devices this outpu
 /proc/tapedevices (which is obsolete) but also includes offline devices. By
 default all tape devices are displayed.
 
-Since SCSI tape devices are accessed differently to channel attached tape
-devices they are only visible if they are known to the SCSI layer. There
-are at least two possible drivers that can claim a SCSI tape device and the
-lstape command tries to find out which one this is. For the generic tape
-and changer driver the device names start with "st" or "sch", while for the
-IBM tape driver this would be "IBMtape" or "IBMchanger". If "N/A" is shown,
-the correct driver could not be obtained.
-
-The serial number of a SCSI tape can be displayed with the --verbose option. If
-there is no sg_inq command available "NO/INQ" is shown as the serial number
-of the tape.
-If no SCSI generic (sg) kernel support is available, "NO/SG" is shown
-as the serial number of the tape and "N/A" for the "Generic" column.
-
 The lstape command without the --ccw-only option causes extra SAN traffic
 for each SCSI tape or changer device by invoking the sg_inq command.
 
@@ -89,6 +75,55 @@ tape devices).
 Limits the output to information about the specified tape device or
 devices only. For CCW-attached devices only.
 
+.SH OUTPUT FIELDS FOR SCSI TAPE/CHANGER DEVICES
+.TP
+.B Generic
+SCSI generic device file for the tape drive, for example /dev/sg0.
+"N/A" if the SCSI generic (sg) kernel functionality is not available.
+.TP
+.B Device
+Main character device node file for accessing the tape drive or medium changer.
+SCSI tape devices are only visible if they are known to the SCSI layer. There
+are at least two possible drivers that can claim a SCSI tape device. The
+lstape command tries to determine the device driver. For the generic tape
+and changer driver the device names start with "st" or "sch", while for the
+IBM tape driver this would be "IBMtape" or "IBMchanger". If "N/A" is shown,
+the device driver could not be determined.
+.TP
+.B Target
+Linux SCSI device name in H:C:T:L format.
+.TP
+.B Vendor
+The vendor field from the SCSI device.
+.TP
+.B Model
+The model field from the SCSI device.
+.TP
+.B Type
+"tapedrv" for a tape drive or "changer" for a medium changer.
+.TP
+.B State
+The state of the SCSI device object in the kernel.
+Any state other than "running" can indicate problems.
+
+.PP
+
+For SCSI devices, the --verbose option additionally displays:
+.TP
+.B HBA
+The device bus-ID of the FCP device
+through which the tape drive is attached.
+"N/A" if device is not attached through zfcp.
+.TP
+.B WWPN
+The WWPN (worldwide port name) of the tape drive in the SAN.
+"N/A" if device is not attached through zfcp.
+.TP
+.B Serial
+The serial number.
+"NO/INQ" if there is no sg_inq command available.
+"NO/SG" if no SCSI generic (sg) kernel support is available.
+
 .SH EXAMPLES
 \fBlstape\fR
 .RS
@@ -99,3 +134,8 @@ List all tape devices that are available
 .RS
 Show all 3490 CCW devices that are online.
 .RE
+
+\fBlstape --scsi-only --verbose\fR
+.RS
+Show all SCSI tape or changer devices with maximum information.
+.RE

Places

File s390-tools-sles15-7-lstape-fix-SCSI-output-description-in-man-page.patch of Package s390-tools (Revision 3a9a54f064c095256124a36daad05854)

Places