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 use SCSI command sets too, they get connected via a translation layer or a bridge device.
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. The mandatory SCSI INQUIRY command is defined in SPC-3. The SCSI Block Commands (SBC) cover direct access devices such as disks. while 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 and 4 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. The majority of these utilities have been ported to the FreeBSD, Solaris, Tru64 and the Windows operating systems (Windows 2000 and later supported).
sg3_utils package installation
# yum install sg3_utils.x86_64
Package Arch Version Repository Size
sg3_utils x86_64 1.37-5.el7 sl 639 k
Installing for dependencies:
sg3_utils-libs x86_64 1.37-5.el7 sl 63 k
Install 1 Package (+1 Dependent package)
Total download size: 701 k
Installed size: 1.8 M
Is this ok [y/d/N]: y
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 below.
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 listing in alphabetical order of the main utilities in the sg3_utils package:
[legacy, use sdparm]
|symbolic decoding (optional changing) of mode pages. Can also output (disk) defect lists. Port of older scsiinfo utility.|
|sgm_dd||sg_dd variant that uses memory mapped IO (only on Linux sg devices)|
|sgp_dd||sg_dd variant that uses POSIX threads|
|sg_bg_ctl||start/stop advance background control operations on disk|
|sg_compare_and_write||if compare successful then write|
|sg_copy_results||used to get the results from the previous sg_xcopy (EXTENDED COPY(LID1))|
|sg_dd||Unix dd command variant, uses SG_IO ioctl to send SCSI commands to copy data. See the sg_dd page. Newer ddpt utility adds features and is ported to "f,s,w"|
|sg_decode_sense||decodes sense data given as a string of hexadecimal bytes or in binary|
|sg_emc_trespass||utility specialized for EMC Clariion series|
|sg_format||format or resize a SCSI disk (with FORMAT UNIT). Alternatively sg_format can format a tape (with FORMAT MEDIUM)|
|sg_get_config||fetch features and profiles of a cd/dvd drive and/or its current media|
|sg_get_lba_status||logical block provisioning support|
|sg_ident||default is to report (fetch) the device identifier. With the '--set' option a new identifier is sent to the device.|
|sg_inq||fetch standard response, VPD pages or version descriptors. Also can perform IDENTIFY (PACKET) DEVICE ATA command. VPD page decoding also performed by sg_vpd and sdparm.|
|sg_logs||fetch log sense pages, decode standard and some vendor pages|
|sg_luns||fetch luns reported by a device (lun 0 or "well known lu")|
|sg_map||shows mapping between sg devices and primary device node (if any). Instead of using sg_map, in lk 2.6 and later the lsscsi utility is recommended.|
|sg_map26||maps between single Linux sg device and primary device node (and vice versa). Also does mapping in to, and out of, sysfs. For the Linux 2.6 series and later. Instead of using sg_map26, the lsscsi utility is recommended.|
|sg_modes||fetch mode pages (output mainly in hex, to decode output use sdparm)|
|sg_opcodes||fetch supported SCSI commands or supported task management functions|
|sg_persist||control persistent reservations and report reservation status|
|sg_prevent||control media removal, mainly for those SCSI devices which have removable media (e.g. CD/DVD and tape drives)|
|sg_raw||send user supplied cdb|
|sg_rbuf||read from SCSI device cache. Typically for testing the SCSI transport (for throughput or errors)|
|sg_rdac||display or modify RDAC redundant controller mode page|
|sg_read||read continually from same offset. Syntax similar to sg_dd (without write side). Can test SCSI device cache and transport performance.|
|sg_read_attr||fetch and decode attributes. Modern tape systems implement this SCSI command.|
|sg_readcap||fetch the number of blocks and the individual block size for disks and CD/DVD media|
|sg_read_buffer||retrieve descriptors, error history or data from device.|
|sg_read_long||read data from given LBA which includes the block and ECC data.|
|sg_reassign||reassign a LBA from one sector on a disk (typically damaged) to a new (spare) sector. User data copied if it is recoverable.|
|sg_referrals||report data segment accessibility from target port groups|
|sg_rep_zones||sends this command to a ZBC (SMR) device and decodes the result. A SAT layer may translate SCSI ZBC commands to ATA ZAC commands that a disk understands|
|sg_requests||fetch sense data from the given device. Modern uses include getting a progress indication (e.g. during a format) or finding the power condition state.|
|sg_reset||Issue a driver, (SCSI) bus or device (target or lun?) reset.|
|sg_reset_wp||sends this command to a ZBC (aka shared magnetic recording [SMR]) device. The corresponding ATA standard is known as ZAC.|
|sg_rmsn||Relatively new command added to SPC-3. Format of response is vendor specific so this utility outputs it in hex (default) or binary.|
|sg_rtpg||Specialized for multi-ported SCSI devices where one port (or a group of them) is preferred for IO over another (or others).|
|sg_safte||fetch information from a SAF-TE processor|
|sg_sanitize||Send SCSI SANITIZE command|
|sg_sat_identify||Send ATA IDENTIFY DEVICE or IDENTIFY PACKET DEVICE commands via the SAT ATA PASS-THROUGH SCSI command.|
|sg_sat_phy_event||Sends an ATA READ LOG EXT command via a SAT to fetch log page 11h which contains SATA phy event counters.|
|sg_sat_read_gplog||Sends an ATA READ LOG (DMA) EXT command via a SAT to fetch a log page|
|sg_sat_set_features||Sends ATA SET FEATURES command via SAT|
|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.|
|shows one device per line, with the device's various names and INQUIRY response string on that line.|
|sg_senddiag||Issues either a default self test or a short/extended foreground/background self test. With no arguments it uses RECEIVE DIAGNOSTIC RESULTS to list all supported diagnostic pages.|
|sg_ses||Fetches status diagnostic pages from, and sends some control pages to, a SCSI Enclosure Services (SES) device. See the sg_ses page.|
|sg_ses_microcode||This microcode (firmware) download (to device) is SES specific. A more general way, typically used with disks, is with sg_write_buffer.|
|sg_start||Controls the power condition state of a SCSI device. Primary use is to spin up and down SCSI disks. Can also load and eject removable media.|
|sg_stpg||Specialized for multi-ported SCSI devices where one port (or a group of them) is preferred for IO over another (or others).|
|sg_sync||Causes disk caches to be flushed to media|
|sg_test_rwbuf||Random pattern written to SCSI device buffer then read back and checked. Used in testing for data corruption.|
|sg_timestamp||Report or set timestamp which is a 48 bit unsigned integer containing the number of milliseconds since 1970-01-01 00:00:00 UTC|
|sg_turs||Issue one or more Test Unit Ready commands. Can be used to time SCSI command overhead.|
|sg_unmap||logical block provisioning support ("Trim" in the ATA world)|
|sg_verify||reads indicated blocks on a SCSI disks, stops on the first error found. Does not yield any data. Useful for media scans.|
|sg_vpd||Decodes standard and some vendor Vital Product Data (VPD) pages.|
|sg_write_buffer||write data; can be used to download firmware|
|sg_write_long||writes to a LBA, data which includes the block and ECC data. Suitable data typically fetched by prior sg_read_long utility.|
|sg_write_same||writes a single block to one or more (consecutive) LBAs. Also supports some logical block provisioning options.|
|sg_write_verify||send one or more commands to consecutive LBAs, reading data from a given file or stdin.|
|sg_wr_mode||writes mode pages supplied in ASCII hex (e.g. from "sg_modes -r") to the SCSI device. See sdparm for another method of setting mode page parameters.|
|sg_xcopy||Uses the EXTENDED COPY(LID1) command to copy between disks. Note: the ddpt utility contains this functionality and adds ODX (a subset of XCOPY(LID4)) capability. ddpt is ported to f,s,w.|
|sg_zone||Sends one of these commands to the given ZBC device. See related sg_rep_zones and sg_reset_wp.|
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.These scripts have an "-h" option for help/usage and a '-v' option for increased verbosity, amongst other options.
|rescan-scsi-bus.sh||0||copy of Kurt Garloff's useful script with additions from Suse amongst others|
|scsi_logging_level||0||create, get or set Linux scsi logging level|
|scsi_mandat||1||check for mandatory SCSI command support|
|scsi_readcap||1 or more||use SCSI READ CAPACITY command on each given device|
|scsi_ready||1 or more||use SCSI TEST UNIT READY on each given <device>|
|scsi_satl||1||check for SCSI to ATA Translation Layer (SATL) support|
|scsi_start||1 or more||use SCSI START STOP UNIT command to start each <device>|
|scsi_stop||1 or more||use SCSI START STOP UNIT command to stop each <device>|
|scsi_temperature||1 or more||use SCSI LOG SENSE command to fetch temperature of each <device>|
Below is a table of other utilities (and scripts) found in sg3_utils and related packages.
|ddpt||dd variant, rewrite of sg_dd. In its own package: ddpt|
|hxascdmp||converts stdin (assumed binary) to ASCII hex and ASCII, sending its output to stdout (like the Unix od command and hexdump in BSD)|
|sas_disk_blink||script in sdparm package. It blinks the ready LED on a SAS disk|
|scsi_inquiry||uses deprecated SCSI_IOCTL_SEND_COMMAND ioctl|
|sdparm||was in the sg3_utils package for a while; now in own package, see sdparm . sdparm manipulates mode pages, reads VPD pages and sends simple commands|
|sg_chk_asc||check asc/ascq codes from www.t10.org page against sg3_utils internal table|
|sg__sat_identify||Simpler version of sg_sat_identify that uses the Linux SG_IO ioctl directly.|
|sg__sat_phy_event||Simpler version of sg_sat_phy_event|
|sg__sat_set_features||Simpler version of sg_sat_set_features that uses the Linux SG_IO ioctl directly.|
|sg_simple1,2,3,4,5||Simple code examples of using the scsi generic (sg) driver interface|
|sg_simple16||Simple code example of sending a 16 byte cdb SCSI READ command|
|smp_discover||discover phy attachments within a SAS expander. In separate package: smp_utils|
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.
|0||no error detected. Utility completed successfully|
||syntax error in command line options or their arguments, or an illegal combination of options|
|2||the device reports that it is not ready for the operation requested. The device may be in the process of becoming ready (e.g. spinning up but not at speed) so the utility may work a little while later|
|3||the device reports a medium or hardware error (or a blank check). For example an attempt to read a corrupted block on a disk will yield this value|
|5||the device reports an "illegal request" with an additional sense code other than "invalid operation code". This is often a supported command with a field set requesting an unsupported capability. For commands that require a "service action" field (e.g. READ CAPACITY(16) ) this value can indicate that the command is not supported|
|6||the device reports a "unit attention" condition. This usually indicates that something, unrelated to the requested command, has occurred (e.g. a device reset) potentially before the current SCSI command was sent. The requested command has not been executed by the device. Note that unit attention conditions are usually only reported once by a device|
|7||the device reports a "data protect" sense key. This implies some mechanism has blocked writes (or possibly all access to the media).|
|9||the device reports an illegal request with an additional sense code of "invalid operation code" which means that the device doesn't support the requested command|
|10||the device reports a "copy aborted" sense key|
|11||the device (or transport) reports an aborted command. In some cases this can be caused by congestion on the transport and retrying the command may be successful|
|14||the device reports a "miscompare" sense key. sg_verify and sg_compare_and_write may report this. Introduced in version 1.37|
|15||the utility is unable to open, close or use the given device or another file. The given file name could be incorrect or there may be permission problems. Adding the '-v' option may give more information|
|20||the device reports it has a check condition but "no sense". Some polling commands (e.g. REQUEST SENSE) can react this way. It is unlikely that this value will occur as an exit status|
|21||the device reports a "recovered error". The requested command was successful. Most likely a utility will report a recovered error to stderr and continue, probably leaving the utility with an exit status of 0|
|24||the device reports a SCSI status of "reservation conflict". This implies that some other initiator holds a reservation on this device; that reservation may block writes or almost all access to that device via the current initiator|
|25||the device reports a SCSI status of "condition met". Currently only the PRE-FETCH command (see SBC-4) yields this status.|
|26||the device reports a SCSI status of "busy". SAM-5 defines this status as the logical unit is temporarily unable to process a command. It is recommended to re-issue the command.|
|27||the device reports a SCSI status of "task set full".|
|28||the device reports a SCSI status of "ACA active". ACA is "auto contingent allegiance" and is seldom used.|
|29||the device reports a SCSI status of "task aborted". SAM-5 says: "This status shall be returned if a command is aborted by a command or task management function on another I_T nexus and the Control mode page TAS bit is set to one".|
|33||the command sent to the device has timed out. This occurs in Linux, in other ports a command timeout will appear as a transport (or OS) error|
|40||the command sent to device has received an "aborted command" sense key with an additional sense code of 0x10. This is related to problems with protection information (PI or DIF). Examples include reading unmapped blocks or blocks that have never been written to (since the last format)|
|97||the response to a SCSI command failed sanity checks|
|98||the device reports it has a check condition but the error doesn't fit into any of the above categories|
|99||any errors that can't be categorized into values 1 to 98 may yield this value. This includes transport and operating system errors|
|126||utility found but could not be executed. Possibly a permissions problem or executable is for a different architecture|
|127||utility not found|
|utility was interrupted by signal <signum>|
|255||utility tried to yield an exit status of 255 or higher|
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 :
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)).
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.