The  Linux sg3_utils package

  1. The  Linux sg3_utils package
    1. Introduction
    2. Contents of sg3_utils
    3. Changing mode page settings
    4. Examples
    5. Notes
    6. Download
    7. Programs from other sources
      1. scu
      2. dt
      3. scsiinfo
      4. scsidev
      5. ddrescue
      6. mapscsi
      7. scsimap
      8. smartsuite
      9. smartmontools
      10. scsirastools
      11. SeaTools
      12. devlabel
      13. plscsi
      14. safte-monitor

Introduction

The sg3_utils package contains utilities that send SCSI commands to "SCSI" devices. As well as devices on transports associated with SCSI (e.g. Fibre Channel (FCP) and the SCSI Parallel Interface(SPI)) many other devices use SCSI command sets. ATAPI cd/dvd drives and SATA disks that use a translation layer or bridge device are examples of devices that use SCSI command sets.

SCSI command sets are divided into a common set and several device class specific sets. The common set of commands is referred to as the SCSI Primary Commands (SPC) with SPC-3 being the most recent standard (or soon will be). The SCSI INQUIRY command whose support is mandatory for all SCSI devices is defined in SPC-3. The SCSI Block Commands (SBC) set covers direct access devices such as disks. The MultiMedia Commands (MMC) set covers CD and DVD drives and the media within them. SCSI command sets and transports definitions can be found at the www.t10.org site with this page giving a good overview: www.t10.org/scsi-3.htm .

The sg3_utils package targets the linux kernel 2.4 and 2.6 series and is still being enhanced. An earlier package called sg_utils targeted the  linux kernel 2.2 series with some support for the 2.0 series. See an earlier version of this web page  for further information about sg_utils.  This document describes version 1.19 of sg3_utils .  A subset of these utilities have been ported to the FreeBSD and Tru64 operating systems.

In the linux kernel 2.4 series most these utilities must be used with a SCSI generic (sg) driver device name (e.g. /dev/sg0). In the lk 2.6 series almost all of these utilities can be used with the primary device names as well (e.g. /dev/sda, /dev/sdc0, /dev/st0 and /dev/hdd (if it is an ATAPI device)). The SCSI generic (sg) interface still represents a cleaner interface than the primary device names since the drivers behind primary device names have their own policies, may interfere with error processing and in some cases run their own state machines.

SCSI utility programs from other sources are listed and briefly described in the final section.

Contents of sg3_utils

Here is a listing in alphabetical order of the utilities in the sg3_utils package:

Utility
Main SCSI commands
subdirectory
Ported
Notes
hxascdmp
-
utils

converts stdin (assumed binary) to ASCII hex and ASCII on stdout (like Unix od command)
isosize
-
archive

size of an ISO 9660 file system, now in the util-linux package
rescan-scsi-bus.sh
-
archive

copy of Kurt Garloff's useful script
scsi_devfs_scan
INQUIRY
archive

more relevant to lk 2.4 (in lk 2.6 sysfs replaces devfs; see lsscsi )
scsi_inquiry
INQUIRY
examples

uses deprecated SCSI_IOCTL_SEND_COMMAND ioctl
sdparm
MODE SENSE/SELECT, INQUIRY
****

was in sg3_utils for a short time; now in own package, see sdparm . sdparm manipulates mode pages, reads VPD pages and sends simple commands.
sginfo
MODE SENSE/SELECT, READ DEFECT


symbolic decoding (optional changing) of mode pages. Can also output (disk) defect lists. In lk 2.4 can be given primary device nodes (e.g. /dev/sda) as well as sg device nodes. See scsiinfo package notes below.
sgm_dd
READ, WRITE


sg_dd variant that uses memory mapped IO (only on sg devices)
sgp_dd
READ, WRITE


sg_dd variant that uses POSIX threads
sgq_dd
READ, WRITE
archive

sg_dd variant that uses asynchronous sg IO calls
sg_dd
READ, WRITE


Unix dd command variant, uses SG_IO ioctl to send SCSI commands to do reads and writes when instructed. See the sg_dd page.
sg_emc_trepass
MODE SELECT


utility specialized for EMC Clariion series
sg_format
FORMAT

fb,t64
format or resize a SCSI disk
sg_get_config
GET CONFIGURATION

fb,t64 fetch features and profiles of a cd/dvd drive and/or its current media
sg_ident
REPORT/SET DEVICE IDENTIFIER

fb,t64 default is to report (fetch) the device identifier. With the '--set' option a new identifier is sent to the device.
sg_inq
INQUIRY

fb,t64 fetch standard response, VPD pages (including device identification) or version descriptors. Also can perform IDENTIFY (PACKET) DEVICE ATA command.
sg_logs
LOG SENSE

fb,t64 fetch log sense pages, decode standard pages
sg_luns
REPORT LUNS

fb,t64 fetch luns reported by a device (lun 0 or "well known lu")
sg_map
INQUIRY


shows mapping between sg devices and primary device node (if any). In lk 2.6 see lsscsi .
sg_map26



maps between single sg device and primary device node (and vice versa). Also does mapping in to and out of sysfs. For the linux 2.6 series.
sg_modes
MODE SENSE

fb,t64 dump mode pages (mainly in hex)
sg_opcodes
REPORT SUPPORTED OPERATION CODES


fetch supported SCSI commands or supported task management functions
sg_persist
PERSISTENT RESERVATION IN/OUT

fb,t64 control reservations and report reservation status
sg_prevent
PREVENT ALLOW MEDIUM REMOVAL

fb,t64 control media removal, mainly for those SCSI devices which have removable media (mainly CD/DVD drives)
sg_rbuff
READ BUFFER


read from SCSI device cache. Typically for testing the SCSI transport (for throughput or errors)
sg_read
READ


read continually from same offset. Syntax similar to sg_dd (without write side). Can test SCSI device cache and transport performance (like sg_rbuff).
sg_readcap
READ CAPACITY

fb,t64 fetch the number of blocks and the individual block size for disks and CD/DVD media
sg_read_long
READ LONG

fb,t64 read from given lba data which includes the block and ECC data.
sg_reassign
REASSIGN BLOCKS

fb,t64 reassign a lba from one sector on a disk (typically damaged) to a new (spare) sector. User data copied if it is recoverable.
sg_requests
REQUEST SENSE

fb,t64 fetch sense data from the given SCSI device. Useful if no autosense , to get progress indication (e.g. during a format) or find the power condition state.
sg_reset
-


Issue a driver, (SCSI) bus or device (target or lun?) reset.
sg_rmsn
READ MEDIA SERIAL NUMBER

fb,t64 Relatively new  command added to SPC-3. Format of response is vendor specific so this utility outputs it in hex.
sg_rtpg
REPORT TARGET PORT GROUPS

fb,t64 Specialized for multi-ported SCSI devices where one port (or a group of them) is preferred for IO over another (or others).
sg_scan
[INQUIRY]


maps each sg device name to the corresponding numeric <host, channel, target', lun> tuple. In lk 2.6 series the "lsscsi -g" command is similar.
sg_senddiag
SEND DIAGNOSTIC

fb,t64 Issues either a default self test or a short/extended foreground/background self test. With no arguments it uses RECEIVE DIAGNOSTIC to list all supported diagnostic pages.
sg_ses
SEND/RECEIVE DIAGNOSTIC

fb,t64 Fetches status diagnostic pages from, and sends some control pages to, a SCSI Enclosure Services (SES) device.
sg_simple1,2,3,4
INQUIRY, TEST UNIT READY
examples

Simple code examples of using the scsi generic (sg) driver interface
sg_simple16
READ
examples

Simple code example of sending a 16 byte cdb SCSI READ command
sg_start
START STOP UNIT

fb,t64 Controls the power condition state of a SCSI device. Primary use is to spin up and down SCSI disks.
sg_sync
SYNCHRONIZE CACHE

fb,t64 Causes disk caches to be flushed to media
sg_test_rwbuf
READ/WRITE BUFFER


Random pattern written to SCSI device buffer then read back and checked. Used in testing for data corruption.
sg_turs
TEST UNIT READY

fb,t64 Issue one or more Test Unit Ready commands. Can be used to time SCSI command overhead.
sg_verify VERIFY
fb,t64 reads indicated blocks on a SCSI disks, stops on the first error found. Does not yield any data. Useful for media scans.
sg_write_long
WRITE LONG

fb,t64 writes to a lba, data which includes the block and ECC data. Suitable data typically fetched by prior sg_read_long utility.
sg_wr_mode
MODE SELECT

fb,t64 writes mode pages supplied in ASCII hex (e.g. from "sg_modes -r") to the given SCSI device. See sdparm for another method of setting mode page parameters.

More SCSI commands may be issued than shown in the "main SCSI commands" column. For example many utilities issue a SCSI INQUIRY command to find out the peripheral device type of the given SCSI device. Some SCSI commands listed above are only relevant to a specific device type (e.g. FORMAT UNIT) and should not be sent to a device belonging to other peripheral device types (and in some cases the logic blocks inappropriate attempts). See the COVERAGE file in the main directory of the tarball for a more exhaustive list of SCSI commands issued by the sg3_utils utilities.

If the "subdirectory" column is empty in the above table then that utility is in the main directory and more documentation can be found in its "man" page. All utilities in the main directory have "man" pages and some in the subdirectories have "man" pages.

If the "Ported" column is empty then the utility is only found in linux. At this time the other ports are to FreeBSD, indicated by "fb" in the "ported" column, and to Tru64, indicated by "t64" in the "ported" column. See the README.freebsd and the README.tru64 files for more information.

In the above table all utilities in the main directory except sgp_dd issue SG_IO ioctls when they want to send SCSI commands to the given device. The sgp_dd utility will only issue SCSI commands using the sg driver's asynchronous ( write()/read() ) interface to device nodes that have the sg driver's major device number (i.e. "char" major 21). This means that all utilities in the main directory are "safe" with any given device node. If the device node does not support the SG_IO ioctl then that is reported and the utility exits. [In version 1.14 sgm_dd also use the sg driver's asynchronous ( write()/read() ) interface but that has been changed to the SG_IO ioctl in version 1.15 since the asynchronous action is not needed. sgm_dd will only use mmapped IO on sg device nodes.]

Irrespective of the Unix device node used to access a device, care should be taken not to interfere with a device while it is "active". For example invoking a "sg_format -F" utility on a disk with mounted file systems on it is going to cause damage.

Changing mode page settings

SCSI devices store settings (metadata) that could possibly be changed by the user (called the "application client" in SCSI jargon) in mode pages. It is a common requirement to find mode page settings and in some cases change them. An example is the Writeback Cache Enable (WCE) bit in the Caching mode page of SCSI disks. Usually the manufacturer's default setting for WCE is set (on) however in some RAID configurations it may be cleared (off).

Generic command line tools to change mode page settings tend to be difficult to use (which in some small part is due to the SCSI rules for manipulating mode pages). Here is a list of some linux utilities for changing mode pages followed by some notes:
The author's recommendation is to use sdparm unless the features of another utility better suit your needs.

Examples

The fundamental SCSI command whose support is mandatory for all SCSI devices is INQUIRY. All devices should respond to a "standard" (i.e. when no Vital Product Pages are requested) INQUIRY.

$ sg_inq /dev/sda
standard INQUIRY:
  PQual=0  Device_type=0  RMB=0  version=0x03  [SPC]
  [AERC=0]  [TrmTsk=0]  NormACA=0  HiSUP=1  Resp_data_format=2
  SCCS=0  ACC=0  TGPS=0  3PC=0  Protect=0
  BQue=0  EncServ=0  MultiP=0  MChngr=0  [ACKREQQ=0]  Addr16=1
  [RelAdr=0]  WBus16=1  Sync=1  Linked=1  [TranDis=1]  CmdQue=1
  Clocking=0x3  QAS=0  IUS=0
    length=144 (0x90)   Peripheral device type: disk
 Vendor identification: SEAGATE
 Product identification: ST318451LW
 Product revision level: 0003
 Unit serial number: xxxxxxxxx

Some SCSI devices have version descriptor information showing which standards (and drafts) they support:

$ sg_inq -d /dev/sdb
standard INQUIRY:
  PQual=0  Device_type=0  RMB=0  version=0x03  [SPC]
  [AERC=0]  [TrmTsk=0]  NormACA=0  HiSUP=0  Resp_data_format=2
  SCCS=0  ACC=0  TGPS=0  3PC=0  Protect=0
  BQue=0  EncServ=0  MultiP=0  MChngr=0  [ACKREQQ=0]  Addr16=1
  [RelAdr=0]  WBus16=1  Sync=1  Linked=1  [TranDis=1]  CmdQue=1
  Clocking=0x0  QAS=0  IUS=0
    length=96 (0x60)   Peripheral device type: disk
 Vendor identification: FUJITSU
 Product identification: MAM3184MP
 Product revision level: 0106
 Unit serial number: xxxxxxxxx

  Version descriptors:
    SAM-2 (no version claimed)
    SPI-3 T10/1302-D revision 10
    SPC ANSI X3.301:1997
    SBC T10/0996-D revision 08c

Many modern SCSI devices also support "Vital Product Data" (VPD) pages. Here is a request to list available VPD pages:

$ sg_inq -e /dev/sg1
VPD INQUIRY, page code=0x00:
   [PQual=0  Peripheral device type: disk]
   Supported VPD pages:
     0x0        Supported VPD pages
     0x80       Unit serial number
     0x83       Device identification

The sg_scan and sg_map utilities show the relationships between sg devices and their <bus, channel, target, lun> tuples and their primary device node names:

Example: given these 3 SCSI devices:
$ cat /proc/scsi/scsi
Attached devices:
Host: scsi1 Channel: 00 Id: 00 Lun: 00
  Vendor: SEAGATE  Model: ST318451LW       Rev: 0003
  Type:   Direct-Access                    ANSI SCSI revision: 03
Host: scsi2 Channel: 00 Id: 04 Lun: 00
  Vendor: PIONEER  Model: DVD-ROM DVD-303  Rev: 1.10
  Type:   CD-ROM                           ANSI SCSI revision: 02
Host: scsi2 Channel: 00 Id: 06 Lun: 00
  Vendor: YAMAHA   Model: CRW4416S         Rev: 1.0g
  Type:   CD-ROM                           ANSI SCSI revision: 02

then the output from sg_scan is:
$ sg_scan
/dev/sg0: scsi1 channel=0 id=0 lun=0  type=0
/dev/sg1: scsi2 channel=0 id=4 lun=0  type=5

/dev/sg2: scsi2 channel=0 id=6 lun=0  type=5

INQUIRY data can be added to that output with the "-i" option. The sg_map utility shows the mapping between scsi generic (sg) devices and the corresponding primary device node. For some peripheral device types, SCSI enclosures for example, there is no mapping and the enclosure device must be accessed via a sg device node.

$ sg_map
/dev/sg0  /dev/sda
/dev/sg1  /dev/scd0
/dev/sg2  /dev/scd1

In the lk 2.6 series of kernels sg_scan and sg_map are less important as most utilities in the sg3_utils package can be issued directly against the primary device node (e.g. /dev/sda).  However the sg driver is still needed to "talk" to devices such as enclosures which have no specialized driver in linux.

Notes

Starting with sg3_utils-1.09 a library called libsgutils is built and is required by most utilities. The library is made up of two source files: sg_lib.c and sg_cmds.c; and their associated header files . The sg_lib.c file contains SCSI command, sense key and additional sense code strings and various related helper functions. The sg_cmds.c file contains low level wrapper functions for commonly used SCSI commands. The library is built both as a shared object and a static library. The binary rpm package only contains the shared library while the sg3_utils-devel rpm package contains the static library, sg_lib.h and sg_cmds.h . If users do not want libraries (shared or static) then they can refer to the "no_lib" subdirectory in the tarball which contains "no_lib" versions of the Makefile and the rpm "spec" file.

Many of the utilities in the sg3_utils package use the SG_IO ioctl (rather than the older write()/read() interface) in the sg driver. In the lk 2.6  series the SG_IO ioctl (or at least a stripped down version of it) has been implemented in the block subsystem. That means that commands that previously only worked on sg device names will now work on block device names as well (e.g. "sg_inq /dev/sda"). To use this facility safely version sg3_utils-1.02 or later should be used. Note that SCSI tape devices (both st and osst device drivers) are char devices and support the SG_IO ioctl from lk 2.6.6 onwards.

See the notes about header file problems in the README file inside each package.

Download

Various tarballs that include the source, a README, CHANGELOG, INSTALL and a Makefile can be found in the table 2 on the main page (link at the bottom of this page). There are also source, i386 binary rpm and deb packages available. Both sg3_utils and the older sg_utils packages can be found on http://freshmeat.net .

Programs from other sources

scu

The SCSI Command Utility (SCU) implements various SCSI commands necessary for normal maintenance and diagnostics of SCSI peripherals. Some of its features include: formatting, scanning for (and reassigning) bad blocks, downloading new firmware, executing diagnostics and obtaining performance information. It is available on several Unix platforms (and NT), however it is only currently available in binary form. See  www.scsifaq.org/RMiller_Tools/index.html or  http://www.scsifaq.org/RMiller_Tools/index.html for more details.

dt

The Data Test (DT) program is modelled on dd's syntax but dt can do a lot more than sequential copies. It is a comprehensive data test program for SCSI devices such as disks, tapes and cdrom/dvds. It is available on several Unix platforms (and NT), and its source is available (unlike its stable mate scu discussed earlier). See www.scsifaq.org/RMiller_Tools/index.html for more details. Both scu and dt are written by Robin T. Miller <Robin.Miller at hp dot com>

scsiinfo

Older package that includes the scsiinfo and scsiformat utilities plus tcl/tk GUI interfaces for those utilities. The last update of the scsiinfo package was in 1997. The function and syntax of the scsiinfo utility have inspired sginfo which now can be considered as a "drop in" replacement for scsiinfo . Recent changes to SCSI standards (e.g. extra and extended mode pages) are reflected in sginfo . In a similar way the sg_format utility can be thought of as a modern replacement for the scsiformat utility.

scsidev

Kurt Garloff <garloff@suse.de> describes this utility thus: "This program scans the SCSI bus and creates device nodes in /dev/scsi/, which have a naming corresponding to their SCSI IDs and LUNs, just like with devfs. (The devfs has no notion of host adapter IDs, scsidev is better here.) Furthermore, the devices are inquired to tell their names and serial numbers. Those can be compared with the entries in a database /etc/scsi.alias and device nodes corresponding to these entries are being built. So,this will even work if you change the SCSI IDs of a device, where the devfs approach would fail". For more information see: www.garloff.de/kurt/linux/scsidev . He also has the useful rescan-scsi-bus.sh script at the same location.

ddrescue

This is another utility from  Kurt Garloff <garloff@suse.de> for rescuing damaged media. It is a variant of dd that will continue passed errors on the input file. It is applicable to any device that can be read by dd (e.g. IDE and SCSI disks, cds and tapes). For more information see: www.garloff.de/kurt/linux/ddrescue

mapscsi

Michael Clark <michael@metaparadigm.com> describes his utility thus: "mapscsi is a small utility that creates a consistent mapping to Linux scsi devices. mapscsi achieves this by creating symbolic links to linux scsi disk devices after scanning all scsi disk devices, finding out their host, channel, id, lun, pci location (if available), Fibre Channel world wide node and port names, loop and port ids (with qla2x00 v4.46.5 driver) vendor, product and serial number details and using this information plus a mapping rules file containing device templates to dynamically create link names". For more information see: http://gort.metaparadigm.com/mapscsi .

scsimap

Steve Cameron <smcameron@yahoo.com> has the following description at his site:

This is a utility to create and maintain symbolic links mapping a predictable set of names to the rather unpredictable names used by linux for disk devices. For example, you might map:
/dev/mydisk1 -> /dev/sda1
/dev/mydisk2 -> /dev/sdb1
/dev/mydisk3 -> /dev/sdc1
If you removed the disk corresponding to /dev/sdb1, then on reboot, /dev/sdc1 will become /dev/sdb1, and /dev/sdc1 will be gone. and your fstab will be wrong, etc. (Especially problematic on a SAN). scsimap will maintain the mapping so that after the reboot, /dev/mydisk3 -> will point to /dev/sdb1 and /dev/mydisk2 will be gone. scsimap also handles later generation Compaq array controllers (those which use the cciss driver.)

See: www.geocities.com/smcameron .

smartsuite

This is a package that supports S.M.A.R.T. capabilities built into modern IDE and SCSI-3 disks. Self-Monitoring, Analysis and Reporting Technology (S.M.A.R.T.) is described at www.pc.ibm.com/us/infobrf/ibsmart.html. For smartsuite see sourceforge.net/projects/smartsuite .

smartmontools

This project has taken over from the aforementioned smartsuite which is currently not actively maintained. See http://smartmontools.sourceforge.net . The author is a maintainer of the SCSI component of this project. [The lead maintainer is Bruce Allen.]

scsirastools

"This project includes changes that enhance the Reliability, Availability and Serviceability (RAS) of the drivers that are commonly used in a Linux software RAID-1 configuration. Other efforts have been made to enable various common hardware RAID adapters and their drivers on Linux." See http://scsirastools.sourceforge.net . The package contains some low level scsi utilities including sgdskfl to load disk firmware, sgmode to get and set mode pages, sgdefects to read primary and grown defect lists and sgdiag to perform format and other test functions.
 

SeaTools

SeaTools is a freely available (binary, not source) utility for disk diagnostics from Seagate which is a disk manufacturer. It can be found at http://www.seagate.com under the support tab. They have both a command line and a graphical utility.  Some of the facilities will work on any SCSI disks while others are Seagate specific. Self tests, mode page settings and formats (to different block sizes) are amongst the facilities available.

devlabel

Devlabel is "a small userspace app which maps symlinks to underlying disk names. It uses [INQUIRY VPD] Page83/Page80 data to track the true locations of disks even if their hd/sd name changes and simply updates the symlink to point to the right place." Sysfs support for the lk 2.6 series and support for multi-path configurations is on the author's "to do" list. See http://www.lerhaupt.com/linux.html .

plscsi

This utility allows arbitrary SCSI commands to be sent to a device. See http://members.aol.com/plscsi . It is similar to FreeBSD's camcontrol command.

safte-monitor

SAF-TE (SCSI Attached Fault-Tolerant Enclosure) is a SCSI command set for monitoring and controlling enclosures and RAIDs. SAF-TE devices report "processor" peripheral device type (0x3) in their INQUIRY responses. More recent products tend to use SES (drafts at http://www.t10.org ) which covers similar functionality. For a SAF-TE monitoring tool for linux see: http://oss.metaparadigm.com/safte-monitor

Return to main page.

Last updated: 27th January 2006