25.2 Linux SCSI Bus commands

* Note use SF Archive commands before using basic Linux commands for troubleshooting.

Binary

Description

Usage/Options

lscsi

Lists all SCSI devices (including SATA and USB devices that use the SCSI subsystem) attached to the system. This is your primary tool for identifying devices.

Installation: 

  • sudo apt update  
  • sudo apt install lsscsi  

Usage:

  • lsscsi  

This will output a list of SCSI devices, showing their bus, target, LUN (Logical Unit Number), and device name. For example:

 

[0:0:0:0]       disk    ATA      ST31000528AS     CC34     /dev/sda  

[1:0:0:0]       cd/dvd  HL-DT-ST DVDRAM GH22NS50  TN02  /dev/sr0     

[2:0:0:0]       disk    WD       My Passport 07A1 1017  /dev/sdb     

[host:channel:target:lun] is the address of the device.

The device type (disk, cd/dvd, etc.) is shown.

The vendor and model are displayed.

The Linux device name (e.g., /dev/sda) is given.

 

Options:

-v: Verbose output, showing more information.

-g: Show the device's /dev name.

-t: Show transport information.

 

sg_scan 

Another tool for scanning the SCSI bus and identifying devices. It's often used to rescan the bus after adding or removing devices.

Installation:

  • sudo apt update  
  • sudo apt install sg3-utils  

Usage:

  • sudo sg_scan -i 

The -i option is important; it prevents the command from actually probing the devices, which can sometimes cause issues. It just reads the existing device information.

  • sudo sg_scan -i -n

Shows numeric IDs

  • sudo sg_scan -e  

This command will provide more detailed information, including enclosure information.

Rescanning the bus: 

To force a rescan of the SCSI bus (useful after adding a new device), you can use:

  • sudo sg_scan -f  

Warning: Rescanning the bus can sometimes cause issues with certain devices. Use with caution, especially on production systems. It's generally safer to reboot the system to detect new devices.

 

sg_inq

Sends a SCSI inquiry command to a device and displays the response. Useful for getting detailed information about a specific device.

Usage:

  • sg_inq /dev/sgX

(replace /dev/sgX with the device path)

  • sg_inq -i /dev/sgX

(shows identification page)

cat /proc/scsi/scsi

 

Displays information about SCSI devices detected by the kernel. This is an older method, but can still be useful.

 

Usage:

  • cat /proc/scsi/scsi  

This will output a list of SCSI devices, similar to lsscsi, but with less formatting.

dmesg

 

Displays kernel messages, which can be helpful for diagnosing SCSI-related issues , which can include information about HBA initialization and errors.

Usage:

  • dmesg | grep scsi  

This will filter the kernel messages to show only those related to SCSI. Look for error messages or warnings. You can also search for specific device names or IDs.

  • dmesg | grep sda  

This will show messages related to /dev/sda.

  • dmesg | grep -i "HBA"
  • dmesg | grep -i "SAS"

 

udevadm info

 

Displays detailed information about a device from the udev device manager. This can be useful for identifying device attributes and properties.

Usage: 

First, identify the device name (e.g., /dev/sda). 

Then use udevadm info with the -a option to show all attributes:

  • udevadm info -a -n /dev/sda  

This will output a large amount of information about the device, including its SCSI bus address, vendor, model, serial number, and other properties.

 

/sys/block/<device_name>

 

The /sys filesystem provides a way to access kernel data structures. The /sys/block/<device_name> directory contains information about block devices (like hard drives).

 

Usage:

  • cd /sys/block/sda  
  • ls -l  
  • cat size  
  • cat queue/rotational  

size: Shows the size of the device in 512-byte sectors.

queue/rotational: Indicates whether the device is rotational (1) or solid-state (0).

 

lspci 

Lists PCI devices and their details. Useful for identifying hardware components and their status.

Usage:

  • lspci

This will display a basic list of all PCI devices found on your system.

  • lspci -v

This provides more detailed information about each device, including IRQ, memory regions, and driver in use.

  • lspci -k

This displays the kernel driver handling each device and lists kernel modules capable of driving the device.

  • lspci -s 0200

This lists only devices belonging to the Ethernet controller class (class code 0200).

  • lspci | grep -i SAS
  • lspci | grep -i emulex
  • lspci | grep -i ATTO

This command pipes the output of lspci to grep, filtering for lines containing "sas" (case-insensitive), which is useful for identifying SAS controllers to filter on just that device.

  • lspci -D

This shows the domain, bus, device, and function numbers for each device.

  • lspci -v -k

This provides detailed information about each device along with the associated kernel drivers.

  • lspci -v -s <bus:device.function>

For detailed info on a specific HBA

  • lspci -vnn |grep -i SAS 

To get specific detailed information on a SAS card including kernel driver being used.

 

 

ltfs

The ltfs command is the primary command-line tool for mounting and managing LTFS (Linear Tape File System) volumes. Its main purpose is to make the data on a tape accessible as if it were on a regular file system, allowing you to interact with the tape using standard file system commands.

In simpler terms, the ltfs command bridges the gap between the sequential nature of tape storage and the random-access nature of file systems. It allows you to treat a tape like a large, removable hard drive.

 

Installation:

  • ltfs –version
  • sudo apt update
  • sudo apt install libfuse2 libxml2
  • sudo dpkg -i <ltfs_package_name>.deb
  • sudo apt-get install -f

Test Installation:

  • sudo mkdir /mnt/ltfs

Create a mount point

  • sudo ltfs /mnt/ltfs

Mount the tape using the ltfs command

  • ll /mnt/ltfs

If the tape mounts successfully, you can access it at /mnt/ltfs. You can then list the contents of the mounted tape

  • sudo umount /mnt/ltfs

Unmount the tape

Once a tape is mounted with ltfs, you can use standard file system commands like ls, cp, mv, rm, mkdir, etc., to interact with the files on the tape

Options:

  • -o readonly 

Mounts the volume in read-only mode. 

  • -o allow_other

Allows other users to access the mounted volume. 

  • -o sync_mount

Mounts the volume synchronously. 

  • -f

Forces the mount or unmount operation. 

Example:

  • ltfs /ltfs/Tape0 -o devname=/dev/sg1 

ltfs: The main LTFS command used to mount LTFS volumes.

/ltfs/Tape0: The mount point where the tape's file system will be accessible. After successful execution, you'll be able to access the files on the tape by navigating to this directory.

-o devname=/dev/sg1: This option specifies which tape drive to use:

-o: Indicates an option is being passed to the LTFS command

devname=/dev/sg1: Specifies that the tape drive is accessible via the SCSI generic device /dev/sg1

What Happens When This Command Runs:

  1. The LTFS driver communicates with the tape drive at /dev/sg1
  2. It reads the LTFS index (metadata) from the tape
  3. It mounts the tape's file system at the /ltfs/Tape0 directory

 

mkltfs

Formats a tape for use with LTFS

Usage: 

  • sudo mkltfs -d /dev/sgX

(formats the tape using the device /dev/sgX) 

Options: 

  • -d <device>

Specifies the SCSI generic device to use.

  • --format-drive

Formats the drive.

  • --erase

Erases the tape before formatting.

  • -v

Verbose output.

 

ltfsck

Checks and repairs an LTFS volume

Usage: 

  • sudo ltfsck /mnt/ltfs

(checks the LTFS volume mounted at /mnt/ltfs) 

Options: 

  • -f

Forces a file system check.

  • -y

Assumes "yes" to all questions.

  • -x

Enables exclusive access to the volume.

 

ltfslabel

Reads or writes the LTFS label on a tape

Usage: 

  • sudo ltfslabel -d /dev/sgX 

(reads the label from the device /dev/sgX) 

Options: 

  • -w: 

Writes a new label.

  • -u <UUID>

Specifies a UUID for the label.

 

ltfsdump

Dumps the contents of an LTFS tape for debugging or recovery

Usage: 

  • sudo ltfsdump /dev/sgX 

(dumps the contents of the tape to standard output) 

Options: 

  • -o <file>: Specifies the output file.

 

ltfsls

Lists the contents of an LTFS tape

Usage: 

  • ltfsls /mnt/ltfs 

(lists the contents of the mounted LTFS volume)

mt

(Magnetic Tape)

The mt command is the primary tool for controlling tape drives. It allows you to perform operations like rewinding, fast-forwarding, spacing files, and ejecting tapes.

Installation: 

  • sudo apt update  
  • sudo apt install mt-st  

 

Basic Usage:

  • mt -f /dev/st0 status  

This command displays the status of the tape drive /dev/st0. Replace /dev/st0 with the correct device name for your tape drive. Common tape device names are /dev/st0, /dev/nst0 (non-rewinding), /dev/tape, etc. The non-rewinding devices are generally preferred for scripting.

Common mt Commands:

Status:

  • mt -f /dev/st0 status

Shows the status of the tape drive

Rewind:

  • mt -f /dev/nst0 rewind  

Rewinds the tape to the beginning.

Eject:

  • mt -f /dev/nst0 offline  

This rewinds the tape and ejects it (if the drive supports it). eject is a synonym for offline.

Fast Forward to End of Data:

  • mt -f /dev/nst0 eom  

Positions the tape at the end of the recorded data. Useful for appending data.

Space Forward File:

  • mt -f /dev/nst0 fsf 1  

Moves forward one file. The 1 can be replaced with the number of files to skip.

Space Backward File:

  • mt -f /dev/nst0 bsf 1  

Moves backward one file.

Space Forward Record:

  • mt -f /dev/nst0 fsr 1  

Moves forward one record.

Space Backward Record:

  • mt -f /dev/nst0 bsr 1  

Moves backward one record.

Write End-of-File Mark:

  • mt -f /dev/nst0 weof  

Writes an end-of-file mark. This is used to separate files on the tape.

Erase:

  • mt -f /dev/st0 erase  

Erases the entire tape. Warning: This will destroy all data on the tape. Use with extreme caution. This command may take a very long time.

 

mtx

(Media Changer)

If you have a tape library (a device with multiple tapes and a robotic arm to load and unload them), the mtx command is used to control the library.

Installation:

  • sudo apt update
  • sudo apt install mtx

Usage:

  • mtx -f /dev/changer status

This displays the status of the tape library. Replace /dev/changer with the correct device name for your changer.

  • mtx -f /dev/changer load 1

Loads the tape from slot 1 into the drive.

mtx -f /dev/changer load <slot> <drive> (loads a tape from a slot into a drive)

  • mtx -f /dev/changer unload 1

Unloads the tape from the drive and returns it to slot 1.

Important Considerations:

Device Names: The tape device names (/dev/st0, /dev/nst0, /dev/tape, /dev/changer) can vary depending on your system configuration. Use lsscsi to identify the correct device names. The "nst" devices are non-rewinding, which are generally preferred for scripting because they don't automatically rewind the tape after each operation.

 

Permissions: You usually need root privileges (using sudo) to access tape devices.

 

Tape Format: The format of the data on the tape depends on the utility used to write it. tar creates a tar archive, while dd writes raw data. You need to use the corresponding utility to read the data.

 

Error Handling: Tape operations can be unreliable. Always check for errors and implement proper error handling in your scripts.

 

Cleaning: Tape drives require periodic cleaning. Consult your tape drive's documentation for cleaning procedures. Some tape drives have a cleaning tape slot. The mtx command can be used to load and unload cleaning tapes.

 

Formatting: Formatting a tape is generally not necessary with modern tape drives. The erase command in mt effectively prepares the tape for reuse. True formatting (writing headers and sector information) is usually handled by the drive itself.

 

sg_logs

Retrieves diagnostic pages from SCSI devices, including tape drives

Usage:

  • sg_logs -a /dev/sgX

Shows all available log pages

Example:

  • sg_logs -p 0x2f /dev/sgX

Shows specific log page

systool

When you need to see low-level details about hardware devices (like SCSI, SAS, or Fibre Channel drives).

systool is a powerful tool for hardware introspection and troubleshooting, especially for storage and bus devices, by providing a direct view into the kernel’s sysfs device tree.

Retrieve the WWN of a device connected to a Emulex card such as a tape library.

Installation:

  • sudo apt update
  • sudo apt install sysfsutils 

Usage:

  • systool -c fchost -v

To view the WWN of a device including the devices connected to the emulex card such as a tape library.

Look for entries under Class Device = "fc_host" that correspond to your Emulex HBA. The output should include port_name and node_name, which are the WWNs (World Wide Names) of the HBA ports and nodes respectively.

Example:

  • systool -c scsi -v

This shows all SCSI devices and their attributes in verbose mode.

  • systool -b pci -v

This lists all PCI devices with detailed information.

  • systool -c scsi -d 2:0:0:0

This shows details for the SCSI device with address 2:0:0:0.