The sg3_utils package

Introduction

The sg3_utils package contains utilities that send SCSI commands to devices. As well as devices on transports traditionally associated with SCSI (e.g. Fibre Channel (FCP), Serial Attached SCSI (SAS) and the SCSI Parallel Interface(SPI)) many other devices use SCSI command sets. ATAPI cd/dvd drives and SATA disks that connect via a translation layer or a 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-5 [INCITS 502-2019] being the most recent standard. The mandatory SCSI INQUIRY command is defined in SPC-5. The SCSI Block Commands (SBC) cover direct access devices such as disks. The MultiMedia Commands (MMC) cover CD, DVD and BD drives and the media within them. SCSI command sets and transport definitions can be found at the www.t10.org . That site includes this helpful diagrammatic overview: www.t10.org/scsi-3.htm .

The sg3_utils package was developed for the Linux kernel 2.4, 2.6, 3, 4, 5 and 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.48 of sg3_utils .  The majority of these utilities have been ported to the FreeBSD, Solaris, Tru64 and the Windows operating systems (Windows 2000 and later supported).

In the Linux kernel (lk) 2.4 series most of these utilities must be used with a SCSI generic (sg) driver device name (e.g. /dev/sg0). In the lk 2.6, 3 and 4 series almost all of these utilities can be used with the primary device names as well (e.g. /dev/sda, /dev/scd0, /dev/st0 and /dev/hdd (if it is an ATAPI device)). From lk 2.6.28 bsg devices can also be used (e.g. /dev/bsg/3:0:0:0 ).

A list of SCSI and storage utility programs can be found on this tools page.

Contents of sg3_utils

This package contains over 50 utilities, their "man" pages, build files and general documentation. The utilities have a command line interface which in general has this form:

 UTILITY_NAME [OPTIONS] DEVICE

No more than one DEVICE name can be given (and in a few cases, no DEVICE name is required). Below is a table in alphabetical order of the utilities in the sg3_utils package:

Table 1. Main utilities in sg3_utils

More SCSI commands may be issued than shown in the Main SCSI commands invoked column. For example many utilities issue a SCSI INQUIRY command to find out the peripheral device type of the given device. Some SCSI commands listed above are only relevant to a specific device type (e.g. FORMAT UNIT for disks) and should not be sent to a device belonging to another peripheral device type. See the COVERAGE file in the main directory for a more exhaustive list of SCSI (and ATA) commands issued by the sg3_utils utilities.

The source code for all the main utilities in table 1 is found in the src sub-directory. Prior to version 1.25 this source was found in the main directory. Each utility listed has a corresponding "man" page in the doc sub-directory. There is also a 'man sg3_utils' page that documents conventions common to all utilities in this package (e.g. their exit status values).

The CLI column indicates what kind of Command Line Interface the utility has. Recent utilities have a CLI based on the getopt_long() function which offers both long option names (e.g. "--verbose") and a short form (e.g. '-v'). Both forms can take an argument. Experience has led to consistent use of various options such as "--help", "--verbose" and "--version" across these utilities and is documented in 'man sg3_utils'. Utilities with this type of CLI are marked with "getopt" in the CLI column. The earlier utilities had an "ad hoc" type CLI that unfortunately lacked consistency and had a mix of long and short forms (with the long form sometime prefixed with "-" and on other occasions with "--"). Utilities with this type of CLI are marked with "adhoc". There is also a group of utilities that are related to the Unix dd command and share its quirky CLI. Finally a group of well used utilities with ad hoc command line interfaces had a getop_long() based interface added in sg3_utils version 1.23 . This group contains significant utilities such as sg_inq, sg_logs and sg_modes. The default CLI for this group is "getopt" but by using "--old" or "-O" as the first option the older ad hoc options can be used. This group will default to the older ad hoc interface if the environment variable SG3_UTILS_OLD_OPTS is defined. Utilities with this type of CLI are marked with "getopt+". The green J blue indicates the utility supports JSON output; plain text output remains the default.

If the Ported column is empty then the utility is only found in Linux. Support for other ports is indicated by "f" for FreeBSD and NetBSD, "s" for Solaris, "t" for Tru64 (OSF), and "w" for Windows. See the README, README.freebsd, README.solaris, README.tru64, README.win32, and the INSTALL files for more information. Linux now has a sub-architecture of Android.

Below is a table of executable scripts (based on the bash shell, other Unix shells may work) found in the scripts directory and installed in some environments. In many cases these scripts use executables listed in table 1. In several cases these scripts overcome the restriction on the utilities in table 1 of only accepting one device per invocation (e.g. scsi_readcap can report on multiple devices while sg_readcap can only report on one). These scripts have an "-h" option for help/usage and a '-v' option for increased verbosity, amongst other options.

Table 2. Executable scripts in scripts directory

Below is a table of other utilities (and scripts) found in sg3_utils and related packages.

Table 3. Other utilities in sg3_utils or related

The directory column contains the name of the sub-directory in which the utility source code is found. Source code in these sub-directories may, in some cases, be built by Makefiles in those sub-directories. See the README file for more information. Not all the code in the examples sub-directory is listed in table 3. Some utilities in these sub-directories have "man" pages.

This paragraph contains Linux specific information. All utilities that issue SCSI commands and that appear in table 1, with the exception of sgp_dd, issue SG_IO ioctls. The sgp_dd utility issues 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 table 1 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. sg3_utils version 1.27 introduces support for bsg: the ./configure stage of the package build needs to find /usr/include/linux/bsg.h and at run time the bsg char device needs to be present in the /proc/devices pseudo file. Then if the device given to utility has a char major that matches bsg then the SG_IO ioctl is used with the sg version 4 interface.

Irrespective of the 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 one or more of its partitions in use (e.g. a mounted file system) is obviously unwise.

Sub directories

The sg3_utils package has several sub-directories that are outlined in the following paragraphs. Prior to sg3_utils version 1.25 the Makefile in the main directory only build code from the main directory (thus, for example, it did not build the code in the examples sub-directory). From sg3_utils version 1.25 the build infrastructure files (i.e. configure.ac, Makefile.am, src/Makefile.am, include/Makefile.am, lib/Makefile.am and doc/Makefile.am) build code found in the lib, src, doc and include sub-directories.

The archive sub-directory contains code that was recently displaced from the src sub-directory. To reduce the size of the overall package, the amount of code carried forward from one release to the next is reduced from time to time.

The debian sub-directory contains rules for building a Linux debian package (i.e. ".deb") from the source code. There is a build_debian.sh shell script in the main directory that can be executed to build a debian package. Note that various distributions that use debian packages and include sg3_utils may vary their build scripts from the ones supplied in this sub-directory.

The doc sub-directory contains a README file which contains urls of web documents related to sg3_utils. The html code used to be present in this sub-directory but it was bloating the package. From sg3_utils version 1.25 the source for the man pages is found in this sub-directory. Those files end with the extension ".8" indicating that they are grouped in the system administration command section. Information common to all utilities has been placed in a man page called sg3_utils.

The examples sub-directory contains relatively simple code examples that may be useful to those trying to use the SCSI pass-through mechanism in the supported operating systems. It also shows the usage of the common library code. There is a test script and data for the sg_persist utility. There is also some test data for sg_reassign and sg_senddiag utilities.

The getopt_long sub-directory contains code for implementing the getopt_long() library call which is not present in Tru64 (osf).

The include sub-directory was introduced in version 1.25 and contains C header files. These header files are common to many utilities in this package. The header files are written in such a way so that they compile cleanly in C++ .

The inhex sub-directory contains examples of hex files containing possible responses for SCSI commands that return a lot of information. An example of this is VPD pages fetched by the SCSI INQUIRY command. Many of the utilities that decode information have a '--in=' or '--inhex=' option that will take one of these hex files rather than send a command to a SCSI device. This is useful for testing and remote support.
The lib sub-directory was introduced in version 1.25 and contains C source files that are used by many of the utilities. Depending on the target architecture and configure options, these files may be build into a library. The source files are written to compile cleanly as C or C++.

The suse sub-directory contains rules for building a Linux Suse package (i.e. ".rpm") from the source code.

The src sub-directory was introduced in version 1.25 . It contains the C source code for each of the main utilities. In most cases each utility has a single C source file (e.g. sg_inq.c for the sg_inq utility). In some cases there may be an additional helper file (e.g. the sg_vpd utility has both sg_vpd.c and sg_vpd_vendor.c).

The scripts sub-directory contain shell scripts for common chores and for checking compliance. Unlike most utilities in the src sub-directory, many of these scripts can take multiple device names. For example: 'scsi_stop /dev/sd*' will attempt to stop (spin down) all SCSI disks. See the README file in that directory for more information.

The testing sub-directory contains programs (C and C++) mainly designed for testing the Linux scsi generic (sg) driver. tst_sg_lib.c does test some functions of this package's library found in the lib sub-directory.

JSON

The utilities in this package still follow the UNIX tradition of doing one thing, sending normal output in plain text to the console (referred to as stdout in Unix shells) and error output (if any) to stderr. Once the task is completed, these utilities exit.. In many cases these utilities decode information provided by a SCSI device. This information is sometimes called metadata (or data about data) to distinguish it from user data, the storage of which is the primary job of storage devices. Over the years the amount of metadata has increased, in parallel with the increases in the amount of data a storage device can hold. It has become desirable to impose more structure in the plain text output of the metadata, especially if other programs with GUI interfaces are trying to format the metadata decoded by the utilities in this package. Enter the JavaScript Object Notation, more commonly known by its abbreviation: JSON .

The information provided by many of these utilities can be categorized into three levels. Starting with the lowest level first:

1. hex output: in this case the response from the SCSI device is simply turned into ASCII hexadecimal and printed out (to stdout) in lines that contain up to 16 bytes each. Depending on the number of –hex options given (more easily expressed in the short form, for example ‘-HHH’) that hex output may have a leading (index) count at the start of each line, and/or a rendering in normal ASCII to the right of each line. This form has proved very useful in error reporting as it can be used for “playback”. For example, a user finds a suspected bug, and sends the hex output file attached to an email reporting the problem. The author can then use the –inhex=FN option (where FN is the name of the file containing the hex) with the faulty utility and thus “replay” the error scenario. The ‘-HHH, -HHHH, -HHHHH” options have been designed specifically to simplify this process. Why do we need hex? Perhaps the author or the SCSI device firmware programmer misread the T10 standards (or drafts). T10 themselves have been known to “screw up” saying one thing at one point in a document and then something else at another point, both referring to the same thing. And then there are vendor-specific commands. A sub-level of hex output is binary output which should be sent to a file rather than to stdout of the console (where it will look like random characters).

2. Plain text output: this takes the response from the device (say a SCSI INQUIRY command to fetch a VPD page), decodes it and presents it as ASCII “art”. Maybe it is presented in a way that it is pleasing to the author’s eye. Nesting is often shown by levels of indentation. Put simply, this form is meant to be parsable by humans, not necessarily by other programs. This is the oldest form of output and is the default in all utilities (that decoded something). One problem with this approach is the ever increasing amount of metadata being held by storage devices. The human can become “overloaded” by the amount of decoded metadata returned by some commands (e.g. sg_ses ) and may need tools to filter out what is important.

3. JSON: this representation has become the structured form of choice and is appearing in other command line tools that decode system information. This package picks up on work done by Christian Franke in the smartmontools project and applies it to this package. Only utilities that decode a significant amount of metadata have been chosen for JSON support. That support comes in the form of two new options: --json[=JO] and –js-file=JFN where JO is a sequence of single letter controls (if given) and JFN is the name of a file the JSON output will be written to.

These three levels are meant to complement one another. It is probably best to start with the middle level: plain text which is the default. If there is something unexpected in the plain text output, the user may wish to drop down to the hex level then start looking at T10 and vendor documents. If all is well and some part of the metadata decoded in plain text is required by another program or script, then the third level: JSON may be useful. Programs like jq (a “command-line JSON processor”) may be helpful. Notice that JSON is only output, so no utility takes JSON as input currently.

SCSI devices primarily return metadata in page form, there are VPD, log, mode and diagnostic pages. Decoding those pages into JSON is supported in this package for the listed page types, apart from mode pages. The sg_modes utility in this package only supplies hex output, thus it doesn’t supply plain text nor JSON output. To get SCSI mode pages decoded in JSON (or plain text) use the sdparm utility in a package of the same name. The sg_modes utility (in this package) and sdparm have been designed to interwork, so sg_modes hex output (e.g. with ‘-HHHH’) can produce a file that can then be read with sdparm’s ‘--inhex=FN’ option.

Help with this package’s JSON usage can be found in ‘man sg3_utils_json’ or the more generally in ‘man sg3_utils’. Each utility has its own manpage.

This JSON support can be viewed as EXPERIMENTAL for the time being. The author is in the strange position of having produced (output) a lot more JSON that he has parsed. A bit like an author who has written more books than she has read. So there may be changes to the JSON output, if a strong case is made. Also questions have been asked about JSON schemas and that is probably some way in the future. In the meantime the –enumerate option (which dumps internal tables used for decoding pages) might be enhanced so that it can be coupled with the –json option to dump internal tables in JSON. This has already be done with sdparm (e.g. ‘sdparm -ea -j’).

Finally the default naming of attributes in JSON seems to be “camel” case in which spaces are suppressed and the first letter of each word is capitalized. On the other hand, T10 field names use “screaming” case which includes spaces and all words are CAPITALIZED. Rather than choose either of those conventions, JSON attribute names in this package use “snake” case in which all words are in lower case and all spaces and other punctuation are replaced by underscore. Snake case is also used in smartmontools’ JSON output, plus Unix/Linux pseudo file systems mostly use this convention. [There are exceptions: there are some field (attribute) names in Linux’s sysfs (typically mounted under /sys) that include spaces.]

Exit status

These command line utilities run as processes and finish with an exit status of 0 when successful. Prior to version 1.21 all errors yielded an exit status of 1. Having finer grain error reporting via the exit status from relatively low level sg3_utils utilities allows higher level scripts and other program wrappers to do more useful error processing.

Indicative exit status values were first added in version 1.22 , the current list is shown below.

Table 4.  Exit status values

Many of the above exit status values will be repeatable so executing the utility again with one or more '-v' options may yield more information. Unit attentions (exit status 6) are only reported once per condition. Notice that some of the lower exit status values (e.g. 2 to 11) correspond to the SCSI sense key values. Exit status 14 (miscompare) was added in version 1.37 while 7, 10, 24 and 40 were added in version 1.39 . Exit status values 0 plus 126 and above are conventions for all Unix executables and scripts (i.e. they are not sg3_utils specific). For examples of bash scripts that use these exit values see the script files in the scripts sub-directory.

Changing mode page settings

SCSI devices store settings (meta-data) that may possibly be changed by the user program (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:

• scsiinfo (old utility): awkward command line interface that requires a double invocation (first to get, second to set). Only mode page fields that the utility knows about can be changed.

• sginfo (sg3_utils version of scsiinfo): same awkward interface as scsiinfo but the mode pages are more up to date. Supports other modern features such as mode subpages.

• sg_wr_mode (sg3_utils): low level mode page settings based on ASCII hex representation. Used with sg_modes to get a mode page in raw form and assumes ACSII hex will be edited. Low level but general.

• sdparm (sdparm): uses acronyms (e.g. WCE) or numeric addressing to fetch and/or change mode page settings. Permits mode pages to be reset to their default settings. The user can choose whether changes are also made to the "saved" mode page values. The numeric addressing allows arbitrary fields to be changed (i.e. sdparm doesn't need to know about a mode page or its field structure in advance).

• sgmode (scsirastools): interactive utility for setting mode pages with data held in preset ".mdf" files. Useful to setting a large number of disks to preset mode page values but awkward for manipulating a specific mode page field.

• hdparm (hdparm): abstracts over ATA (mainly) and SCSI (where convenient) disks. Write caching can be turned on and off but that is one of the few mode page fields that can be changed on a SCSI device.

• blktool (blktool): a newer and cleaner version of hdparm which targets the Linux kernel 2.6 series. For SCSI devices only a relatively small (but important) number of mode page fields can be changed.

• vendor specific (e.g. seatools from Seagate): several vendors have utilities like this. Worth investigating and often useful with disks from other manufacturers. Vendor extensions can be controlled (e.g. Seagate's desktop/server mode (also see sdparm's man page about this particular feature)).

The author's recommendation is to use sdparm unless the features of another utility better suit your needs.

Aside: device meta-data that cannot be changed by the user is often placed in Vital Product Data (VPD) pages. The VPD pages can be accessed via the SCSI INQUIRY command. The sg_vpd utility in this package and sdparm utility list the contents of various VPD pages.

Examples

Most of these examples use Linux device names. See the device naming page for appropriate device names in other supported operating systems. Apart from the examples below, many of the utilities in this package have an EXAMPLES section in their manpages. Also several utilities have their own web page on this site (e.g. the sg_ses and sg_dd pages).

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 LU_CONG=0 version=0x06 [SPC-4]
 [AERC=0] [TrmTsk=0] NormACA=0 HiSUP=1 Resp_data_format=2
 SCCS=0 ACC=0 TPGS=0 3PC=0 Protect=1 [BQue=0]
 EncServ=0 MultiP=1 (VS=0) [MChngr=0] [ACKREQQ=0] Addr16=0
 [RelAdr=0] WBus16=0 Sync=0 [Linked=0] [TranDis=0] CmdQue=1
 [SPI: Clocking=0x0 QAS=0 IUS=0]
 length=144 (0x90) Peripheral device type: disk
Vendor identification: SEAGATE 
Product identification: ST200FM0073 
Product revision level: CB02
Unit serial number: xxxxxxx

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

For displaying VPD pages, sg_vpd (or sdparm) may be a better choice than sg_inq as sg_vpd has a simpler, less cluttered command line interface and additional support for vendor specific VPD pages.

# sg_vpd /dev/sdh
Supported VPD pages VPD page:
 Supported VPD pages [sv]
 Unit serial number [sn]
 Implemented operating definition (obs) [iod]
 Device identification [di]

The following displays a subset of the device identification VPD page, namely the designators for the target port:

# sg_vpd --page=di_port /dev/sdh
Device Identification VPD page:
 Target port:
 designator type: Relative target port, code_set: Binary
 transport: Serial Attached SCSI (SAS)
 Relative target port: 0x1
 designator type: NAA, code_set: Binary
 transport: Serial Attached SCSI (SAS)
 0x5222222000000f9e

The sg_scan and sg_map utilities show the relationships between Linux sg devices, 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. Instead of using sg_map, in lk 2.6 and later the lsscsi utility is recommended.

Some examples of the use of the sg_persist utility can be found in the source tarball in examples/sg_persist_tst.sh . Some more information about that utility can be found in examples/transport_ids.txt .

The Windows port has its own sg_scan utility which attempts to list the common storage devices, one per line. On recent Windows operating systems sg_scan needs to be run in a shell with Administrator privileges. Volume names corresponding to a storage device (or a partition on that device) are shown in brackets. Here are two examples, the second one adds a bus type field:

$ sg_scan
PD0 [C] FUJITSU MHY2160BH 0000
PD1 [DF] WD 2500BEV External 1.05 WD-WXE90
CDROM0 [E] MATSHITA DVD/CDRW UJDA775 CB03

$ sg_scan -b
PD0 [C] <Ata > FUJITSU MHY2160BH 0000
PD1 [DF] <Usb > WD 2500BEV External 1.05 WD-WXE90
CDROM0 [E] <Atapi> MATSHITA DVD/CDRW UJDA775 CB03

The PD0 device name is a shortened form of PhysicalDrive0 and corresponds to volume C: . The USB connected PD1 contains two partitions recognized by Windows and they are D: and F: . Apart from the storage device names PD<n> and CDROM<n>, there is TAPE<n> for tape drives.

The following example in Linux specific. More and more VPD pages responses are being made available in the sysfs pseudo file system. Those responses are in binary which makes them a challenge to decode with command line tools. On the other hand they don't need root permissions (or similar) to access unlike almost all of these utilities which send a SCSI command to the device.

$ lsscsi 
[0:0:0:0]    disk    Linux    scsi_debug       0189  /dev/sda 
[N:0:1:1]    disk    INTEL SSDPEKKF256G7L__1                    /dev/nvme0n1
$
$
$ cd /sys/class/scsi_device/0:0:0:0/device
$ ls
blacklist       eh_timeout                          generic        model                 scsi_device   type      wwid
block           evt_capacity_change_reported        inquiry        power                 scsi_disk     uevent
bsg             evt_inquiry_change_reported         iocounterbits  queue_depth           scsi_generic  vendor
delete          evt_lun_change_reported             iodone_cnt     queue_ramp_up_period  scsi_level    vpd_pg0
device_blocked  evt_media_change                    ioerr_cnt      queue_type            state         vpd_pg80
device_busy     evt_mode_parameter_change_reported  iorequest_cnt  rescan                subsystem     vpd_pg83
driver          evt_soft_threshold_reached          modalias       rev                   timeout       vpd_pg89
$
$ sg_vpd -r -I vpd_pg83
Device Identification VPD page:
  Addressed logical unit:
    designator type: T10 vendor identification,  code set: ASCII
      vendor id: Linux   
      vendor specific: scsi_debug      2000
    designator type: NAA,  code set: Binary
      0x33333330000007d0
  Target port:
    designator type: Relative target port,  code set: Binary
     transport: Serial Attached SCSI Protocol (SPL-4)
      Relative target port: 0x1
    designator type: NAA,  code set: Binary
     transport: Serial Attached SCSI Protocol (SPL-4)
      0x32222220000007ce
    designator type: Target port group,  code set: Binary
     transport: Serial Attached SCSI Protocol (SPL-4)
      Target port group: 0x100
  Target device that contains addressed lu:
    designator type: NAA,  code set: Binary
     transport: Serial Attached SCSI Protocol (SPL-4)
      0x32222220000007cd
    designator type: SCSI name string,  code set: UTF-8
     transport: Serial Attached SCSI Protocol (SPL-4)
      SCSI name string:
      naa.32222220000007CD
$

As can been seen, VPD page 0x83 which is the device identification VPD page is decoded. The -I or --inhex= option takes a file containing the response. The -r or --raw option indicates the contents of that file is in binary as by default sg_vpd assumes the contents of the file is ASCII hexadecimal. The INQUIRY response in binary is also in the same sysfs directory:

$ ./sg_vpd -p sinq -r -I inquiry
standard INQUIRY:
  PQual=0  Device_type=0  RMB=0  LU_CONG=0  version=0x07  [SPC-5]
  [AERC=0]  [TrmTsk=0]  NormACA=0  HiSUP=0  Resp_data_format=2
  SCCS=0  ACC=0  TPGS=0  3PC=0  Protect=0  [BQue=0]
  EncServ=0  MultiP=1 (VS=0)  [MChngr=0]  [ACKREQQ=0]  Addr16=0
  [RelAdr=0]  WBus16=0  Sync=0  [Linked=1]  [TranDis=0]  CmdQue=1
  Vendor_identification: Linux   
  Product_identification: scsi_debug      
  Product_revision_level: 0189
$

This time sg_vpd needed a bit of help with the -p sinq (or --page=sinq) option as the standard INQUIRY response is not formatted in the fashion of the other VPD responses. This invocation 'sg_inq -r -I inquiry' will output the same thing.

libsgutils

The various utilities in this package were found to have a lot of common code (e.g. use of the SCSI INQUIRY command and SCSI error processing). So a library called libsgutils has been created. Following Unix conventions the library is packaged in two parts: the main part is needed at runtime by the utilities in this package; and a second "dev" package is required for any code that wants to compile and built using this library. The "dev" package contains the header files defining the libraries API amongst other things.

The library API is relatively stable but is expanded and sometimes changed in response to changes by www.t10.org . The most recent Debian naming of this library was libsgutils2-2 . Some other packages depend on this library.

Shared and static libraries are built by default. To build these utilities so they don't depend on this shared library use './configure --disable-shared'.

NVME Support

On one hand NVM Express (usually written as "NVMe") doesn't have much in common with SCSI. They have different command sets and don't share many transports. The SOP/PQI project which uses the SCSI command set over PCIe (PCI Express) has not caught on, probably closely related to NVMe's success on PCIe.

On the other hand both SCSI and NVMe offer alternative approaches to accessing solid state disks (SSDs), approaches that have much in common. SCSI has been around a little longer (1981 compared to 2011) . In the early days of NVMe there was a SCSI to NVMe Translation Layer (SNTL) but that was dropped in 2017 from the Linux kernel as Intel were not prepared to support it any longer. Strange, since the equivalent mechanism for (mainly) SATA disks called SCSI to ATA Translation (SAT) has been quite successful both for SATA and the SAS (SCSI serial protocol).

There are some signs of the two protocols co-existing with the NVME-MI (Management Interface) group accepting the SES-3 standard for (storage) enclosure management. To this end two NVME-MI commands have been added: SES Send and SES Receive. The library underpinning sg3_utils has been extended to detect NVMe devices in Linux and FreeBSD (not yet working for Windows) has been extended and to pass-through SCSI SEND DIAGNOSTIC and RECEIVE DIAGNOSTIC RESULTS commands to those new NVME-MI commands. The sg3_utils library implements a small SNTL that emulates the mandatory SPC commands (e.g. INQUIRY and REPORT LUNS) and a few others so that the sg_ses utility can interact with a NVMe enclosure with almost no code changes to sg_ses itself. sg_inq has been modified to detect NVMe devices and partially decode the Identify Controller and Identify namespace responses. The lsscsi utility (see the lsscsi package) now lists NVMe namespaces (after SCSI logical units) and NVMe controllers (after SCSI hosts (HBAs)).

The sg_senddiag utility applied to a NVMe device will attempt to tunnel the associated data in NVME-MI SES Send and SES Recieve commands. That should fail unless the NVMe controller has an enclosure attached. The sg_raw command can issue NVME Admin command. The sg_inq command has two modes when applied to a NVME (namespace or controller); without options it will send Identify controller and namespace (assuming there is one) and partially decode the response; with the "--page=sinq" option ("sinq" means standard Inquiry, so for SCSI devices that is the same as the default (no option) usage) will issue a SCSI INQUIRY which the above mentioned SNTL will emulate an INQUIRY response.

Since there is no standard SNTL, this package has taken the liberty of defining its own "vendor specific" VPD page: 0xde . When fetched (with sg_inq, sg_vpd or sdparm) on a NVMe device it will yield the Identify controller response which is 4096 bytes long.

Download and build

Several recent versions of the sg3_utils package are listed below. The tarballs contain README, CHANGELOG (renamed "ChangeLog" in version 1.25), INSTALL, COVERAGE and CREDITS files plus man pages as well as source and build files.  Here is the most recently released sg3_utils ChangeLog .

Table 5. sg3_utils tarballs and packages

The zip files below are built with MingGW-W64. They also build clean with cygwin but then they depend on a proprietary dll. The sg3_utils_man_html.tgz file is a tarball of man pages converted to html by man2html.

Table 6. sg3_utils Windows zip packages

Version 1.25 of sg3_utils first added autotools, an improvement on hand-crafted Makefiles. Now a build from source requires this sequence: './autogen.sh ; ./configure ; make ; make install' executed in the top level directory of the source package. The requirement to call ‘./autogen.sh’ first (or ‘./bootstrap’ which is a synonym) was added in version 1.48 of sg3_utils . The reduces the size of the source package as script files like ‘./configure’ are large and complex. The downside is that more automake/autoconf packages may be needed on the build system. The configure.ac and several Makefile.am files guide the autotools build. If these files are changed then the './autogen.sh' script should be re-run. The autotools based logic builds the code found in the src, lib, include and doc sub-directories. The utils, testing and examples sub-directories still have hand-crafted Makefiles. If the ./configure or  make steps fail then it may be worth trying to run the './autogen.sh' script as there are many versions of autotools and the mysterious libtool to be found. Many options can be given to ./configure  and ./configure --help  will list many of those options. By default  './configure ' will produce Makefiles that install under the /usr/local directory (e.g. executables are placed in the /usr/local/bin directory). To place executables in the more usual (at least for Linux) /usr/bin directory then use './configure --prefix=/usr ; make ; make install'.

Starting in version 1.48 of sg3_utils, if the code is fetched from a git or subversion repository, then ./autogen.sh (or ./bootstrap ) needs to be run. However the 1.48 tarballs provided already have ./autogen.sh executed on them so the canonical build sequence once again becomes ./configure ; make ; make install . This may make builds a bit easier to perform on embedded (or stripped down) systems.

* tarball also available with a ".tar.gz" extension and bzipped with a ".tar.bz2" extension. From version 1.31 the tarball is available with a ".xz" extension as well.

** Around the time of Fedora 11, RedHat changed their package checksums from MD5 to SHA256. The above rpm packages are typically built with the most recent Fedora at time of release. It has been reported that adding "--nomd5" to the rpm command line may help with unpacking problems. See bug 490613 at RedHat's bugzilla.

*** Some browsers (e.g. firefox) may interpret a file with an extension of "rpm" as an audio file. In which case press the right button over the link and select "Save link as ..." to download the file.


Below is the most recent version of the sg_utils package which targets the Linux kernel 2.2 series with some support for the lk 2.0 series. No further work is being done on this package.

Table 7.  sg_utils tarballs and packages

Github mirror

The sg3_utils package is developed by the author using subversion. Subversion revisions, which are ascending integers, can be seen in the ChangeLog file. Many users have asked for git access so Hannes Reinecke has set up this git mirror on github:

• https://github.com/hreinecke/sg3_utils

• maintainer's mirror: https://github.com/doug-gilbert/sg3_utils

Updates are sent to that mirror from time to time, typically every 3 months. Betas (identified by their subversion revision number) are placed relatively often on the main page, typically more often than updates appearing on github. Please report any problems to me or report them as an "Issues" or supply a patch via a pull request on the github reflector.

Return to main page.

Last updated: 1st August 2023