FCL--FOSS Check List 1.0 Project Information 1.1 Name of project/component Sg3 Utilities 1.2 Author of document xiao.l@sun.com 2.0 Project Summary 2.1 Project Description The Sg3 Utilities contain 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)) and 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. There are Fedora, Debian and Windows packages available. 2.2 Release binding What is is the release binding? (see http://opensolaris.org/os/community/arc/policies/release-taxonomy/) [ ] Major [x] Minor [ ] Patch or Micro [ ] Unknown -- ARC review required 2.3 Type of project Is this case a Linux Familiarity project? [x] Yes [ ] No 2.4 Originating Community 2.4.1 Community Name Sg3 Utilities http://sg.danny.cz/sg/sg3_utils.html It is active now, the latest code update is on 26th July, 2008. The code has been updated several times since Jan 2008. 2.4.2 Community Involvement Indicate Sun's involvement in the community [ ] Maintainer [ ] Contributor [x] Monitoring Will the project team work with the upstream community to resolve architectural issues of interest to Sun? [x] Yes [ ] No - briefly explain Will we or are we forking from the community? [ ] Yes - ARC review required prior to forking [x] No 3.0 Technical Description 3.1 Installation & Sharable 3.1.1S Solaris Installation - section only required for Solaris Software (see http://opensolaris.org/os/community/arc/policies/install-locations/ for details) Does this project follow the Install Locations best practice? [x] Yes [ ] No - ARC review required Does this project install into /usr under [sbin|bin|lib|include|man|share]? [x] Yes [ ] No or N/A Does this project install into /opt? [ ] Yes - explain below [x] No or N/A Does this project install into a different directory structure? [ ] Yes - ARC review required [x] No or N/A Do any of the components of this project conflict with anything under /usr? (see http://opensolaris.org/os/community/arc/caselog/2007/047/ for details) [ ] Yes - explain below [x] No If conflicts exist then will this project install under /usr/gnu? [ ] Yes [ ] No - ARC review required [x] N/A Is this project installing into /usr/sfw? [ ] Yes - ARC review required [x] No 3.1.1W Windows Installation - section only required for Windows Software (see http://sac.sfbay/WSARC/2002/494 for details) Does this project install software into a :\Program Files\Sun\ or :\Sun\ directory? [ ] Yes [ ] No - ARC review required Does the project use the Windows registry? [ ] Yes [ ] No - ARC review required Does the project use HKEY_LOCAL_MACHINE\SOFTWARE\Sun Microsystems\\ for the registry key? [ ] Yes [ ] No - ARC review required Is the project's stored location HKEY_LOCAL_MACHINE\SOFTWARE\Sun Microsystems\\\Path? [ ] Yes [ ] No - ARC review required 3.1.2 Share and Sharable Does the module include any components that are used or shared by other projects? [ ] Yes [x] No If yes are these components packaged to be shared with the other FOSS? [ ] Yes [ ] No - ARC review required [x] N/A Are these components already in the Solaris WOS? [ ] Yes [x] No - continue with next section (section 3.2) If yes are these newer versions being delivered? [ ] Yes [ ] No - ARC review required If yes are the newer versions replacing the existing versions? [ ] Yes [ ] No - ARC review required 3.2 Exported Libraries Are libraries being delivered by this project? [ ] Yes [x] No - continue with next section (section 3.3) Are 64-bit versions of the libraries being delivered? [ ] Yes [ ] No - ARC review required Are static versions of the libraries being delivered? [ ] Yes - ARC review required [ ] No 3.3 Services and the /etc Directory (see http://opensolaris.org/os/community/arc/policies/SMF-policy/) Does the project integrate anything into /etc/init.d or /etc/rc?.d? [ ] Yes - ARC review required [x] No Does the project integrate any new entries into /etc/inittab or /etc/inetd.conf? [ ] Yes - ARC review required [x] No Does the project integrate any private non-public files into /etc/default or /etc/ configuration files? [ ] Yes - ARC review required [x] No Does the service manifests method context grant rights above that of the noaccess user and basic privilege set? [ ] Yes - ARC review required [x] No 3.4 Security 3.4.1 Secure By Default (see http://opensolaris.org/os/community/arc/policies/secure-by-default/ for details) (see http://www.opensolaris.org/os/community/arc/policies/NITS-policy/ for details) (see parts of http://opensolaris.org/os/community/arc/policies/SMF-policy/ for addtional details) Are there any network services provided by this project? [ ] Yes [x] No - continue with the next section (section 3.4.2) Are network services enabled by default? [ ] Yes - ARC review required [ ] No [ ] N/A Are network services automatically enabled by the project during installation? [ ] Yes - ARC review required [ ] No [ ] N/A Are inbound network communications denied by default? [ ] Yes [ ] No - ARC review required [ ] N/A Is inbound data checked to prevent content-based attacks? [ ] Yes [ ] No - ARC review required [ ] N/A Is the outbound receiver authenticated? [ ] Yes [ ] No - ARC review required [ ] N/A Is the receiver authenticated prior to receiving any sensitive outbound communication? [ ] Yes [ ] No - ARC review required [ ] N/A 3.4.2 Authorization (see http://opensolaris.org/os/community/arc/bestpractices/rbac-intro/ and http://opensolaris.org/os/community/arc/bestpractices/rbac-profiles/ and http://opensolaris.org/os/community/arc/bestpractices/rbac-profiles/ for details) Are there any setuid/setgid privileged binaries in the project? [ ] Yes - ARC review required [x] No - continue with next section (section 3.4.3) If yes then are the setuid/setgid privileges handled by the use of roles? [ ] Yes [ ] No - ARC review required 3.4.3 Auditing (see http://opensolaris.org/os/community/arc/policies/audit-policy/ for details) (see http://opensolaris.org/os/community/arc/caselog/2003/397 for details) Does this component contain administrative or security enforcing software? [ ] Yes - ARC review required [x] No - continue to next section (section 3.4.4) (see http://opensolaris.org/os/community/arc/caselog/2003/397 for details) Do the components create audit logs detailing what took place including what event took place, who was involved, when the event took place? [ ] Yes - ARC contract and Audit project team review required [ ] No - ARC review required 3.4.4 Authentication (see http://opensolaris.org/os/community/arc/policies/PAM/) Do the components contain any authentication code? [ ] Yes [x] No - continue to next section (section 3.4.5) If yes do the components use PAM (plugable authentication modules) for authentication? [ ] Yes [ ] No - ARC review required If yes is a single PAM session maintained during authentication? [ ] Yes [ ] No - ARC review required If yes are the components sufficiently privileged to allow the requested operations (authentication, password change, process credential manipulation, audit state initialization)? [ ] Yes - briefly describe below [ ] No - ARC review required 3.4.5 Passwords (see http://opensolaris.org/os/community/arc/bestpractices/passwords-cli/ and http://opensolaris.org/os/community/arc/bestpractices/passwords-files/ for details) Do any of the components for the project deal with passwords? [ ] Yes [x] No - continue to next section (section 3.4.6) If yes are these passwords entered via the CLI or environment? [ ] Yes - ARC review required [ ] No Are passwords stored within the file system for the component? [ ] Yes [ ] No - continue to next section (section 3.4.6) If yes are the permissions on the file such to protect exposing the password(s)? [ ] Yes [ ] No - ARC review required 3.4.6 General Security Questions (see http://opensolaris.org/os/community/arc/bestpractices/security-questions/ for details) Are there any network protocols used by this project? [ ] Yes [x] No - continue with the next section (section 3.5) Do the components use standard network protocols? [ ] Yes [ ] No - ARC review required Do network services for the project make decisions based upon user, host or service identities? [ ] Yes - explain below [ ] No [ ] N/A Do the components make use of secret information during authentication and/or authorization? [ ] Yes - explain below [ ] No [ ] N/A 3.5 Networking Do the components access the network? [ ] Yes [x] No - continue with the next section (section 3.6) If yes do the components support IPv6? [ ] Yes [ ] No - ARC review required 3.6 Core Solaris Components Do the components of this project compete with or duplicate core Solaris components? [ ] Yes - ARC review required [x] No Examples of Core Solaris Components include but are not limited to: Secure By Default Authorizations PAM -- Plugable Authentication Module Privilege PRM -- Process Rights Management -- Privilege Audit xVm -- Virtualization zones / Solaris Containers PRM -- Process Rights Management RBAC -- Role Based Access Control TX / Trusted Extensions ZFS SMF -- Service Management Facility FMA -- Fault Management Architecture SCF -- Smart Card Facility IPsec 4.0 Interfaces (see http://www.opensolaris.org/os/community/arc/policies/interface-taxonomy/ for details) 4.1 Exported Interfaces Interface Name Classification Comments --------------------------- ------------------- --------------------------- SUNWsg3utilsu Uncommitted Package name SUNWsg3utilsr Uncommitted Package name /usr/sbin/sg_get_config Uncommitted Command /usr/sbin/sg_ident Uncommitted Command /usr/sbin/sg_inq Uncommitted Command /usr/sbin/sg_logs Uncommitted Command /usr/sbin/sg_luns Uncommitted Command /usr/sbin/sg_modes Uncommitted Command /usr/sbin/sg_opcodes Uncommitted Command /usr/sbin/sg_persist Uncommitted Command /usr/sbin/sg_prevent Uncommitted Command /usr/sbin/sg_raw Uncommitted Command /usr/sbin/sg_rdac Uncommitted Command /usr/sbin/sg_read_buffer Uncommitted Command /usr/sbin/sg_read_long Uncommitted Command /usr/sbin/sg_readcap Uncommitted Command /usr/sbin/sg_reassign Uncommitted Command /usr/sbin/sg_requests Uncommitted Command /usr/sbin/sg_rmsn Uncommitted Command /usr/sbin/sg_rtpg Uncommitted Command /usr/sbin/sg_safte Uncommitted Command /usr/sbin/sg_sat_identify Uncommitted Command /usr/sbin/sg_sat_set_features Uncommitted Command /usr/sbin/sg_senddiag Uncommitted Command /usr/sbin/sg_ses Uncommitted Command /usr/sbin/sg_start Uncommitted Command /usr/sbin/sg_stpg Uncommitted Command /usr/sbin/sg_sync Uncommitted Command /usr/sbin/sg_turs Uncommitted Command /usr/sbin/sg_verify Uncommitted Command /usr/sbin/sg_vpd Uncommitted Command /usr/sbin/sg_wr_mode Uncommitted Command /usr/sbin/sg_write_buffer Uncommitted Command /usr/sbin/sg_write_long Uncommitted Command /usr/lib/libsgutils.so Private Symbolic link /usr/lib/libsgutils.so.1 Private Symbolic link /usr/lib/libsgutils.so.1.0.0 Private Shared library file /usr/share/man/man1m/sg_read_long.1m Uncommitted Manpage /usr/share/man/man1m/sg_safte.1m Uncommitted Manpage /usr/share/man/man1m/sg_senddiag.1m Uncommitted Manpage /usr/share/man/man1m/sg_wr_mode.1m Uncommitted Manpage /usr/share/man/man1m/sg_stpg.1m Uncommitted Manpage /usr/share/man/man1m/sg_persist.1m Uncommitted Manpage /usr/share/man/man1m/sg_ses.1m Uncommitted Manpage /usr/share/man/man1m/sg_opcodes.1m Uncommitted Manpage /usr/share/man/man1m/sg_get_config.1m Uncommitted Manpage /usr/share/man/man1m/sg_read_buffer.1m Uncommitted Manpage /usr/share/man/man1m/sg_luns.1m Uncommitted Manpage /usr/share/man/man1m/sg_requests.1m Uncommitted Manpage /usr/share/man/man1m/sg_prevent.1m Uncommitted Manpage /usr/share/man/man1m/sg_rdac.1m Uncommitted Manpage /usr/share/man/man1m/sg_rtpg.1m Uncommitted Manpage /usr/share/man/man1m/sg_sat_identify.1m Uncommitted Manpage /usr/share/man/man1m/sg_start.1m Uncommitted Manpage /usr/share/man/man1m/sg_verify.1m Uncommitted Manpage /usr/share/man/man1m/sg_modes.1m Uncommitted Manpage /usr/share/man/man1m/sg_readcap.1m Uncommitted Manpage /usr/share/man/man1m/sg_sat_set_features.1m Uncommitted Manpage /usr/share/man/man1m/sg_rmsn.1m Uncommitted Manpage /usr/share/man/man1m/sg3_utils.1m Uncommitted Manpage /usr/share/man/man1m/sg_ident.1m Uncommitted Manpage /usr/share/man/man1m/sg_vpd.1m Uncommitted Manpage /usr/share/man/man1m/sg_inq.1m Uncommitted Manpage /usr/share/man/man1m/sg_raw.1m Uncommitted Manpage /usr/share/man/man1m/sg_turs.1m Uncommitted Manpage /usr/share/man/man1m/sg_sync.1m Uncommitted Manpage /usr/share/man/man1m/sg_logs.1m Uncommitted Manpage /usr/share/man/man1m/sg_format.1m Uncommitted Manpage /usr/share/man/man1m/sg_reassign.1m Uncommitted Manpage /usr/share/man/man1m/sg_write_long.1m Uncommitted Manpage /usr/share/man/man1m/sg_write_buffer.1m Uncommitted Manpage 4.2 Imported Interfaces Interface Name Classification Comments --------------------------- -------------------- -------------------------- USCSICMD Committed PSARC 1997/288 (originally Evolving) Appendix B - Suggested case materials 1. man pages SG3_UTILS SG_GET_CONFIG(8) NAME sg_get_config - sends a SCSI GET CONFIGURATION command SYNOPSIS sg_get_config [--brief] [--current] [--help] [--hex] [--inner-hex] [--list] [--rt=RT] [--starting=FC] [--verbose] [--version] DEVICE DESCRIPTION Sends a SCSI GET CONFIGURATION command to DEVICE and decodes the response. The response includes the features and pro- files of the device. Typically these devices are CD and DVD players that may (but not necessarily) have media in them. These devices may well be connected via ATAPI, USB or IEEE 1394 transports. In such cases they are "SCSI" devices only in the sense that they use the "Multi-Media command" set (MMC). MMC is a specialized SCSI command set whose defini- tion can be found at http://www.t10.org . This utility is based on the MMC-4 and MMC-5 draft stan- dards. See section 5 on "Features and Profile for Multi_Media devices" for more information on specific feature parameters and profiles. The manufacturer's product manual may also be useful. Since modern DVD writers support many features and profiles, the decoded output from this utility can be large. There are various ways to cut down the output. If the --brief option is used only the feature names are shown and the feature parameters are not decoded. Alternatively if only one feature is of interest then this combination of options is appropriate: "--rt=2 --starting=FC". Another possibility is to show only the features that are relevant to the media in the drive (i.e. "current") with the "--rt=1" option. OPTIONS Arguments to long options are mandatory for short options as well. -b, --brief show the feature names but don't decode the parameters of those features. When used with --list outputs known feature names but not known profile names. -c, --current output features marked as current. This option is equivalent to '--rt=1'. -h, --help output the usage message then exit. -H, --hex sg3_utils-1.24 Last change: February 2007 1 SG3_UTILS SG_GET_CONFIG(8) output the response in hex (don't decode response). -i, --inner-hex decode to the feature name level then output each feature's data in hex. -l, --list list all known feature and profile names. Ignore the device name (if given). Simply lists the feature names and profiles (followed by their hex values) that this utility knows about. If --brief is also given then only feature names are listed. -r, --rt=RT where RT is the field of that name in the GET CONFI- GURATION cdb. Allowable values are 0, 1, 2, or 3 . The command's action also depends on the value given to the --starting=FC option. The default value is 0. When RT is 0 then all features, regardless of currency, are returned (whose feature code is greater than or equal to FC given to --starting=). When RT is 1 then all current features are returned (whose feature code is greater than or equal to FC). When RT is 2 then the feature whose feature code is equal to FC, if any, is returned. When RT is 3 the response is reserved (prob- ably yields an "illegal field in cdb" error). To sim- plify the meanings of the RT values are: 0 : all features, current on not 1 : only current features 2 : only feature whose code is FC 3 : reserved -s, --starting=FC where FC is the feature code value. This option works closely with the --rt=RT option. The FC value is in the range 0 to 65535 (0xffff) inclusive. Its default value is 0. A value prefixed with "0x" (or a trailing 'h') is interpreted as hexadecimal. -v, --verbose increase the level of verbosity, (i.e. debug output). -V, --version print the version string and then exit. NOTES There are multiple versions of the MMC (draft) standards: MMC [1997], MMC-2 [2000], MMC-3 [2002], MMC-4 and MMC-5. The first three are now ANSI INCITS standards with the year they became standards shown in brackets. The draft immedi- ately prior to standardization can be found at http://www.t10.org . In the initial MMC standard there was sg3_utils-1.24 Last change: February 2007 2 SG3_UTILS SG_GET_CONFIG(8) no GET CONFIGURATION command and the relevant information was obtained from the "CD capabilities and mechanical status mode page" (mode page 0x2a). It was later renamed the "MM capabilities and mechanical status mode page" and has been made obsolete in MMC-4 and MMC-5. The GET CONFIGURATION com- mand was introduced in MMC-2 and has become a replacement for that mode page. New features such as support for "BD" (blue ray) media type can only be found by using the GET CONFIGURATION command. Hence older CD players may not sup- port the GET CONFIGURATION command in which case the "MM capabilities ..." mode page can be checked with sdparm(8), sginfo(8) or sg_modes(8). In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic (sg) device. In the 2.6 series block devices can also be specified. For example "sg_get_config /dev/hdc" will work in the 2.6 series kernels as long as /dev/hdc is an ATAPI device. In the 2.6 series external DVD writers attached via USB could be queried with "sg_get_config /dev/scd1" for example. EXIT STATUS The exit status of sg_get_config is 0 when it is successful. Otherwise see the sg3_utils(8) man page. AUTHORS Written by Douglas Gilbert. REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2004-2007 Douglas Gilbert This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sginfo(8), sg_modes(8), sg_inq(8), sg_prevent(8), sg_start(8) [all in sg3_utils], sdparm(8) sg3_utils-1.24 Last change: February 2007 3 SG3_UTILS SG_IDENT(8) NAME sg_ident - sends a SCSI REPORT or SET IDENTIFYING INFORMA- TION command SYNOPSIS sg_ident [--ascii] [--clear] [--help] [--itype=IT] [--raw] [--set] [--verbose] [--version] DEVICE DESCRIPTION Send a SCSI REPORT IDENTIFYING INFORMATION or SET IDENTIFY- ING INFORMATION command to DEVICE. Prior to SPC-4 (revison 7) these commands were called REPORT DEVICE IDENTIFIER and SET DEVICE IDENTIFIER respectively. SCSI devices that sup- port these two commands allow users to write (set) identify- ing information and report it back at some later time. The information is persistent (i.e. stored on some non-volatile medium within the SCSI device that will survive a power outage). Typically the space allocated for the information is lim- ited: SPC-4 (revision 7) states that for information type 0, the minimum length is 64 bytes and the maximum is 512 bytes. For other information types (1 to 126 inclusive) the maximum length is 256 bytes. Also information types 1 to 126 (inclusive) should contain a null terminated UTF-8 string. The author has seen older disks that only support 16 bytes. The default action when no options are given is to invoke the Report Identifying Information command with the informa- tion type defaulting to zero. Error reports are sent to stderr. By default the information is shown in ASCII-HEX (up to 16 bytes per line) with an ASCII representation to the right with dots replacing non printable characters. OPTIONS Arguments to long options are mandatory for short options as well. -A, --ascii invokes the Report Identifying Information command and if anything is found interprets it as ASCII (or UTF-8 depending on the locale) and prints the information to stdout. -C, --clear invokes the Set Identifying Information command with an information length of zero. This has the effect of clearing the existing information. -h, --help output the usage message then exit. sg3_utils-1.23 Last change: January 2007 1 SG3_UTILS SG_IDENT(8) -i, --itype=IT where IT is the information type. Defaults to zero. The maximum value is 127 which is special and cannot be used with --set or --clear. The information type of 127 (if supported) causes the REPORT IDENTIFYING INFORMA- TION command to respond with a list of available infor- mation types and their maximum lengths in bytes. The odd numbered information types between 3 and 125 (inclusive) are not to be used (as they clash with the SCC-2 standard). -r, --raw invokes the Report Identifying information command and if anything is found sends the information (which may be binary) to stdout. Nothing else is sent to stdout however error reports, if any, are sent to stderr. -S, --set first reads stdin until an EOF is detected then invokes the Set Identifying Information command to set what has been fetched from stdin as the information. The amount of data read must be between 1 and 512 bytes length (inclusive). -v, --verbose increase the level of verbosity, (i.e. debug output). -V, --version print the version string and then exit. This utility permits users to write their own identifying information to their SCSI devices. There are several other types of descriptors (or designators) that the user cannot change. These include the SCSI INQUIRY command with its standard vendor and product identification strings and the product revision level; plus the large amount of information provided by the "Device Identification" VPD page (see sg_vpd). There is also the READ MEDIA SERIAL NUMBER command (see sg_rmsn). The MMC-4 command set for CD and DVDs has a "media serial number" feature (0x109) [and a "logical unit serial number" feature]. These can be viewed with the sg_get_config utility. EXAMPLES First, to see if there is an existing information whose for- mat is unknown (for information type 0), use no options: # sg_ident /dev/sdb 00 31 32 33 34 35 36 37 38 39 30 1234567890 If it is ASCII then it can printed as such: sg3_utils-1.23 Last change: January 2007 2 SG3_UTILS SG_IDENT(8) # sg_ident --ascii /dev/sdb 1234567890 The information can be copied to a file, cleared and then re-asserted with this sequence: # sg_ident --raw /dev/sdb > t # sg_ident --clear /dev/sdb # cat t | sg_ident --set /dev/sdb EXIT STATUS The exit status of sg_ident is 0 when it is successful. Oth- erwise see the sg3_utils(8) man page. AUTHORS Written by Douglas Gilbert. REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2005-2007 Douglas Gilbert This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_vpd(sg3_utils), sg_rmsn(sg3_utils), sg_get_config(sg3_utils) sg3_utils-1.23 Last change: January 2007 3 SG3_UTILS SG_INQ(8) NAME sg_inq - sends a SCSI INQUIRY or ATA IDENTIFY (PACKET) DEV- ICE command and outputs the response SYNOPSIS sg_inq [--ata] [--cmddt] [--descriptors] [--extended] [--help] [--hex] [--id] [--len=LEN] [--page=PG] [--raw] [--verbose] [--version] [--vpd] DEVICE sg_inq [-36] [-a] [-A] [-b] [-c] [-cl] [-d] [-e] [-h] [-H] [-i] [-l=LEN] [-m] [-M] [-o=OPCODE_PG] [-p=VPD_PG] [-P] [-r] [-s] [-v] [-V] [-x] [-36] [-?] DEVICE DESCRIPTION This utility by default sends a SCSI INQUIRY command to the given device and then outputs the response. All SCSI devices are meant to respond to a "standard" INQUIRY command with at least a 36 byte response (in SCSI 2 and higher). An INQUIRY is termed as "standard" when both the EVPD and CmdDt (obsolete) bits are clear. This utility supports two command line syntaxes, the pre- ferred one is shown first in the synopsis and explained in this section. A later section on the old command line syntax outlines the second group of options. An important "non-standard" INQUIRY page is the Device Iden- tification Vital Product Data (VPD) page [0x83]. Since SPC-3, support for this page has been flagged as mandatory. The --id option decodes this page. To get fine grained decoding of this VPD page and others, including some vendor specific VPD pages, see the sg_vpd(8) utility. If the DEVICE exists and the SCSI INQUIRY fails (because the SG_IO ioctl is not supported) then an ATA IDENTIFY (PACKET) DEVICE is tried. If it succeeds then device identification strings are output. The --raw and --hex options can be used to manipulate the output. If the --ata option is given then the SCSI INQUIRY is not performed and the DEVICE is assumed to be ATA (or ATAPI). The reference document used for interpreting an INQUIRY is T10/1713-D Revision 11 (SPC-4, 14 May 2007) found at http://www.t10.org . Obsolete items in the standard INQUIRY response are displayed in brackets. The reference document for the ATA IDENTIFY (PACKET) DEVICE command is ATA8-ACS found at http://www.t13.org . OPTIONS Arguments to long options are mandatory for short options as well. The options are arranged in alphabetical order based on the long option name. sg3_utils-1.25 Last change: August 2007 1 SG3_UTILS SG_INQ(8) -a, --ata Assume given DEVICE is an ATA or ATAPI device which can receive ATA commands from the host operating system. Skip the SCSI INQUIRY command and use either the ATA IDENTIFY DEVICE command (for nonpacket devices) or the ATA IDENTIFY PACKET DEVICE command. To show the response in hex, add a '--verbose' option. This option is only available in Linux. -c, --cmddt set the Command Support Data (CmdDt) bit (defaults to clear(0)). Used in conjunction with the --page=PG option where PG specifies the SCSI command opcode to query. When used twice (e.g. '-cc') this utility forms a list by looping over all 256 opcodes (0 to 255 inclusive) only outputting a line for found commands. The CmdDt bit is now obsolete. It has been replaced by the REPORT SUPPORTED OPERATION CODES command, see the sg_opcodes(8) utility. -d, --descriptors decodes and prints the version descriptors found in a standard INQUIRY response. There are up to 8 of them. Version descriptors indicate which versions of stan- dards and/or drafts the DEVICE complies with. The nor- mal components of a standard INQUIRY are output (typi- cally from the first 36 bytes of the response) followed by the version descriptors if any. -e see entry below for --vpd. -E, -x, --extended prints the extended INQUIRY VPD page [0x86]. -h, --help print out the usage message then exit. When used twice, after the usage message, there is a list of available abbreviations than can be given to the --page=PG option. -H, --hex rather than decode a standard INQUIRY response, a VPD page or command support data; print out the response in hex to stdout. Error messages and warnings are typi- cally output to stderr. When used twice with the ATA Information VPD page [0x89] decodes the start of the response then output the ATA IDENTIFY (PACKET) DEVICE response in hexadecimal bytes (not 16 bit words). When used three times with the ATA Information VPD page [0x89] or the --ata option, this utility outputs the ATA IDENTIFY (PACKET) DEVICE response in hexadecimal words suitable for input to 'hdparm --Istdin'. See sg3_utils-1.25 Last change: August 2007 2 SG3_UTILS SG_INQ(8) note below. -i, --id prints the device identification VPD page [0x83]. -l, --len=LEN the number LEN is the "allocation length" field in the INQUIRY cdb. This is the (maximum) length of the response to be sent by the device. The default value of LEN is 0 which is interpreted as: first request is for 36 bytes and if necessary execute another INQUIRY if the "additional length" field in the response indi- cates that more than 36 bytes is available. If LEN is greater than 0 then only one INQUIRY command is per- formed. See paragraph below about "36 byte INQUIRYs". -O, --old switch to older style options. -p, --page=PG the PG argument can be either a number of an abbrevia- tion for a VPD page. To enumerate the available abbre- viations for VPD pages use '-hh' or a bad abbreviation (e.g, '--page=xxx'). When the --cmddt option is given (once) then PG is interpreted as an opcode number (so VPD page abbreviations make little sense). -r, --raw output the response in binary to stdout. Error messages and warnings, if any, are sent to stderr. -v, --verbose increase level of verbosity. Can be used multiple times. -V, --version print out version string then exit. -e, --vpd set the Enable Vital Product Data (EVPD) bit (defaults to clear(0)). Used in conjunction with the --page=PG option where PG specifies the VPD page number to query. If the --page=PG is not given then PG defaults to zero which is the "Supported VPD pages" VPD page. NOTES Some devices with weak SCSI command set implementations lock up when they receive commands they don't understand (or even response lengths that they don't expect). Such devices need to be treated carefully, use the '--len=36' option. Without this option this utility will issue an initial standard INQUIRY requesting 36 bytes of response data. If the device sg3_utils-1.25 Last change: August 2007 3 SG3_UTILS SG_INQ(8) indicates it could have supplied more data then a second INQUIRY is issued to fetch the longer response. That second command may lock up faulty devices. ATA or ATAPI devices that use a SCSI to ATA Translation layer (see SAT at www.t10.org) may support the ATA Informa- tion VPD page. This returns the IDENTIFY (PACKET) DEVICE response amongst other things. The ATA Information VPD page can be fetched with '--page=ai'. In the INQUIRY standard response there is a 'MultiP' flag which is set when the device has 2 or more ports. Some ven- dors use the preceding vendor specific ('VS') bit to indi- cate which port is being accessed by the INQUIRY command (0 -> relative port 1 (port "a"), 1 -> relative port 2 (port "b")). When the 'MultiP' flag is set, the preceding vendor specific bit is shown in parentheses. SPC-3 compliant dev- ices should use the device identification VPD page (0x83) to show which port is being used for access and the SCSI ports VPD page (0x88) to show all available ports on the device. In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic (sg) device. In the 2.6 series block devices (e.g. disks and ATAPI DVDs) can also be specified. For example "sg_inq /dev/sda" will work in the 2.6 series kernels. From lk 2.6.6 other SCSI "char" device names may be used as well (e.g. "/dev/st0m"). ATA DEVICES There are two major types of ATA devices: non-packet devices (e.g. ATA disks) and packet devices (ATAPI). The majority of ATAPI devices are CD/DVD drives in which the ATAPI transport carries the MMC set (i.e. a SCSI command set). Further, both types of ATA devices can be connected to a host com- puter via a "SCSI" (or some other) transport. When an ATA disk is controlled via a SCSI (or non-ATA) transport then two approaches are commonly used: tunnelling (e.g. STP in Serial Attached SCSI (SAS)) or by emulating a SCSI device (e.g. with a SCSI to ATA translation layer, see SAT at www.t10.org ). Even when the physical transport to the host computer is ATA (especially in the case of SATA) the operat- ing system may choose to put a SAT layer in the driver "stack" (e.g. libata in Linux). The main identifying command for any SCSI device is an INQUIRY. The corresponding command for an ATA non-packet device is IDENTIFY DEVICE while for an ATA packet device it is IDENTIFY PACKET DEVICE. When this utility is invoked for an ATAPI device (e.g. a CD/DVD drive with "sg_inq /dev/hdc") then a SCSI INQUIRY is sent to the device and if it responds then the response to sg3_utils-1.25 Last change: August 2007 4 SG3_UTILS SG_INQ(8) decoded and output and this utility exits. To see the response for an ATA IDENTIFY PACKET DEVICE command add the --ata option (e.g. "sg_inq --ata /dev/hdc). This utility doesn't decode the response to an ATA IDENTIFY (PACKET) DEVICE command, hdparm does a good job at that. The '-HHH' option has been added for use with either the '--ata' or '--page=ai' option to produce a format acceptable to "hdparm --Istdin". An example: 'sg_inq --ata -HHH /dev/hdc | hdparm --Istdin'. See hdparm. EXIT STATUS The exit status of sg_inq is 0 when it is successful. Other- wise see the sg3_utils(8) man page. OLDER COMMAND LINE OPTIONS The options in this section were the only ones available prior to sg3_utils version 1.23 . In sg3_utils version 1.23 and later these older options can be selected by either set- ting the SG3_UTILS_OLD_OPTS environment variable or using --old (or -O) as the first option. -36 only requests 36 bytes of response data for an INQUIRY. Furthermore even if the device indicates in its response it can supply more data, a second (longer) INQUIRY is not performed. This is a paranoid setting. Equivalent to '--len=36' in the main description. -a fetch the ATA Information VPD page [0x89]. Equivalent to '--page=ai' in the main description. This page is defined in SAT (see at www.t10.org). -A Assume given DEVICE is an ATA or ATAPI device. Equivalent to --ata in the main description. -b decodes the Block Limits VPD page [0xb0]. Equivalent to '--page=bl' in the main description. This page is defined in SBC-2 (see www.t10.org). -c set the Command Support Data (CmdDt) bit (defaults to clear(0)). Used in conjunction with the -o=OPCODE_PG option to specify the SCSI command opcode to query. Equivalent to --cmddt in the main description. -cl lists the command data for all supported commands (fol- lowed by the command name) by looping through all 256 opcodes. This option uses the CmdDt bit which is now obsolete. See the sg_opcodes(8) utility. Equivalent to '--cmddt --cmddt' in the main description. -d decodes depending on context. If -e option is given, or sg3_utils-1.25 Last change: August 2007 5 SG3_UTILS SG_INQ(8) any option that implies -e (e.g. '-i' or '-p=80'), then this utility attempts to decode the indicated VPD page. Otherwise the version descriptors (if any) are listed following a standard INQUIRY response. In the version descriptors sense, equivalent to --descriptors in the main description. -e enable (i.e. sets) the Vital Product Data (EVPD) bit (defaults to clear(0)). Used in conjunction with the -p=VPD_PG option to specify the VPD page to fetch. If -p=VPD_PG is not given then VPD page 0 (list supported VPD pages) is assumed. -h outputs INQUIRY response in hex rather than trying to decode it. Equivalent to --hex in the main descrip- tion. -H same action as -h. Equivalent to --hex in the main description. -i decodes the Device Identification VPD page [0x83]. Equivalent to --id in the main description. This page is made up of several "designation descriptors". If -h is given then each descriptor header is decoded and the identifier itself is output in hex. To see the whole VPD 0x83 page response in hex use '-p=83 -h'. -m decodes the Management network addresses VPD page [0x85]. Equivalent to '--page=mna' in the main descrip- tion. -M decodes the Mode page policy VPD page [0x87]. Equivalent to '--page=mpp' in the main description. -N switch to the newer style options. -o=OPCODE_PG used in conjunction with the -e or -c option. If nei- ther given then the -e option assumed. When the -e option is also given (or assumed) then the argument to this option is the VPD page number. The argument is interpreted as hexadecimal and is expected to be in the range 0 to ff inclusive. Only VPD page 0 is decoded and it lists supported VPD pages and their names (if known). To decode the mandatory device identification page (0x83) use the -i option. A now obsolete usage is when the -c option is given in which case the argument to this option is assumed to be a command opcode number. Recent SCSI draft standards have moved this facility to a separate command (see sg_opcodes(8)). Defaults to 0 so if -e is given without this option then VPD page 0 is output. sg3_utils-1.25 Last change: August 2007 6 SG3_UTILS SG_INQ(8) -p=VPD_PG same action as -o=OPCODE_PG option described in the previous entry. Since the opcode value with the CmdDt is now obsolete, the main use of this option is to specify the VPD page number. The argument is inter- preted as hexadecimal and is expected to be in the range 0 to ff inclusive. Defaults to 0 so if -e is given without this option then VPD page 0 is output. -P decodes the Unit Path Report VPD page [0xc0] which is EMC specific. Equivalent to '--page=upr' in the main description. -r outputs the response in binary to stdout. Equivalent to --raw in the main description. Can be used twice (i.e. '-rr' (and '-HHH' has same effect)) and if used with the -A or -a option yields output with the same format as "cat /proc/ide/hd/identify" so that it can then be piped to "hdparm --Istdin". -s decodes the SCSI Ports VPD page [0x88]. Equivalent to '--page=sp' in the main description. -v increase level of verbosity. Can be used multiple times. -V print out version string then exit. -x decodes the Extended INQUIRY data VPD [0x86] page. Equivalent to '--page=ei' in the main description. -? output usage message and exit. Ignore all other parame- ters. AUTHOR Written by Doug Gilbert REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2001-2007 Douglas Gilbert This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_opcodes(8), sg_vpd(8), hdparm(8), sgdiag(scsirastools) sg3_utils-1.25 Last change: August 2007 7 SG3_UTILS SG_LOGS(8) NAME sg_logs - access log pages with SCSI LOG SENSE command SYNOPSIS sg_logs [--all] [--brief] [--control=PC] [--help] [--hex] [--list] [--maxlen=LEN] [--name] [--page=PG[,SPG]] [--paramp=PP] [--pcb] [--ppc] [--raw] [--reset] [--select] [--sp] [--temperature] [--transport] [--verbose] [--version] DEVICE sg_logs [-a] [-A] [-b] [-c=PC] [-h] [-H] [-l] [-L] [-m=LEN] [-n] [-p=PG[,SPG]] [-paramp=PP] [-pcb] [-ppc] [-r] [-select] [-sp] [-t] [-T] [-v] [-V] [-?] DEVICE DESCRIPTION This utility sends a SCSI LOG SENSE command to the DEVICE and then outputs the response. The LOG SENSE command is used to fetch log pages. Known log pages are decoded by default. When the --reset and/or --select option is given then a SCSI LOG SELECT command is issued to reset parameters. In SPC-4 revision 5 a subpage code was introduced to both the LOG SENSE and LOG SELECT command. At the same time a page code field was introduced to the to the LOG SELECT com- mand. The log subpage code can range from 0 to 255 (0xff) inclusive. The subpage code value 255 can be thought of as a wildcard. This utility supports two command line syntaxes, the pre- ferred one is shown first in the synopsis and explained in this section. A later section on the old command line syntax outlines the second group of options. OPTIONS Arguments to long options are mandatory for short options as well. -a, --all outputs all the log pages supported by the device. This requires a two stage process: first the "supported log pages" log page is fetched, then for each entry in the response, the corresponding log page is fetched and displayed. When used twice (e.g. '-aa') all log pages and subpages are fetched. -b, --brief shorten the amount of output for some log pages. For example the Tape Alert log page only outputs parameters whose flags are set when --brief is given. -c, --control=PC accepts 0, 1, 2 or 3 for the PC argument: sg3_utils-1.24 Last change: April 2007 1 SG3_UTILS SG_LOGS(8) 0 : current threshold values 1 : current cumulative values 2 : default threshold values 3 : default cumulative values The default value is 1 (i.e. current cumulative values). -h, --help print out the usage message then exit. -H, --hex The default action is to decode known mode page numbers (and subpage numbers) into text. When this option is used once, the response is output in hexadecimal. -l, --list lists the names of all logs sense pages supported by this device. This is done by reading the "supported log pages" log page. When used twice (e.g. '-ll') lists the names of all logs sense pages and subpages supported by this device. There is a list of common log page codes below. -m, --maxlen=LEN sets the "allocation length" field in the LOG SENSE cdb. The is the maximum length in bytes that the response will be. Without this option (or LEN equal to 0) this utility first fetches the 4 byte response then does a second access with the length indicated in the first (4 byte) response. Negative values and 1 for LEN are not accepted. Responses can be quite large (e.g. the background scan results log page) and this option can be used to limit the amount of information returned. -n, --name decode some log pages into 'name=value' entries, one per line. The name contains no space and may be abbre- viated and the value is decimal unless prefixed by '0x'. Nesting is indicated by leading spaces. This form is meant to be relatively easy to parse. -O, --old switch to older style options. -p, --page=PG[,SPG] log page code to access. PG is expected to be a decimal number between 0 and 63 inclusive. A hexadecimal number can be specified by a leading "0x" or a trailing "h". Common log page codes are listed below. Optionally SPG, a subpage code, can be given. SPG is expected to be a decimal number between 0 and 255 inclusive. sg3_utils-1.24 Last change: April 2007 2 SG3_UTILS SG_LOGS(8) -P, --paramp=PP PP is the parameter pointer value to place in a field of that name in the LOG SENSE cdb. A decimal number in the range 0 to 65535 (0xffff) is expected. When a value greater than 0 is given the --ppc option should be selected. The default value is 0. -q, --pcb show Parameter Control Byte settings (only relevant when log parameters being output in ASCII). -Q, --ppc sets the Parameter Pointer Control (PPC) bit in the LOG SENSE cdb. Default is 0 (i.e. cleared). -r, --raw output the response in binary to stdout. Error messages and warnings are output to stderr. -R, --reset use SCSI LOG SELECT command (PCR bit set) to reset the all log pages (or the given page). [SPC-4 (rev 6) doesn't say that a given log (sub)page can be reset yet.] Exactly what is reset depends on the accompanying SP bit (i.e. --sp option which defaults to 0) and the PC ("page control") value (which defaults to 1). Sup- plying this option implies the --select option as well. This option seems to clear error counter log pages but leaves pages like self-test results, start-stop cycle counter and temperature log pages unaffected. This option may be required to clear log pages if a counter reaches its maximum value since the log page in which the counter is found will remain "stuck" until some- thing is done. -S, --select use a LOG SELECT command. The default action (i.e. when neither this option nor --reset is given) is to do a LOG SENSE command. When this option is given, the SP bit (i.e. --sp option which defaults to 0), the PC ("page control") value (which defaults to 1) and the PCR bit (i.e. --reset option which defaults to 0) are placed in the LOG SELECT cdb. At some stage the log page and subpage options may also be active [but SPC-4 (rev 6) doesn't say that]. -s, --sp sets the Saving Parameters (SP) bit. Default is 0 (i.e. cleared). When set this instructs the device to store the current log page parameters (as indicated by the DS and TSD parameter codes) in some non-volatile location. Hence the log parameters will be preserved across power sg3_utils-1.24 Last change: April 2007 3 SG3_UTILS SG_LOGS(8) cycles. This option is typically not needed, especially if the GLTSD flag is clear in the control mode page as this instructs the device to periodically save all saveable log parameters to non-volatile locations. -t, --temperature outputs the temperature. First looks in the temperature log page and if that is not available tries the Infor- mational Exceptions log page which may also have the current temperature (especially on older disks). -T, --transport outputs the transport ('Protocol specific port') log page. Equivalent to setting '--page=18h'. -v, --verbose increase level of verbosity. -V, --version print out version string then exit. NOTES This utility will usually do a double fetch of log pages with the SCSI LOG SENSE command. The first fetch requests a 4 byte response (i.e. place 4 in the "allocation length" field in the cdb). From that response it can calculate the actual length of the response which is what it asks for on the second fetch. This is typical practice in SCSI and guaranteed to work in the standards. However some older dev- ices don't comply. For those devices using the --maxlen=LEN option will do a single fetch. A value of 252 should be a safe starting point. Various log pages hold information error rates, device tem- perature, start stop cycles since device produced and the results of the last 20 self tests. Self tests can be ini- tiated by the sg_senddiag(8) utility. The smartmontools package provides much of the information found with sg_logs in a form suitable for monitoring the health of SCSI disks and tape drives. Here is a list of log pages that are decoded by this util- ity. [The code values can be given to '--page=' as is, with a trailing "h" instead of the leading "0x", or as their decimal equivalents.]: 0x0 Supported log pages 0x0,0xff Supported log pages and subpages 0x1 Buffer overrun/underrun 0x2 Write error counter 0x3 Read error counter 0x4 Read reverse error counter sg3_utils-1.24 Last change: April 2007 4 SG3_UTILS SG_LOGS(8) 0x5 Verify error counter 0x6 Non-medium error 0x7 Last n error events 0x8 Format status (sbc-2) 0xb Last n deferred errors or asynchronous events 0xc Sequential access device (ssc-2) 0xd Temperature 0xe Start-stop cycle counter 0x10 Self-test results 0x15 Background scan results (sbc-3) 0x17 Non-volatile cache (sbc-3) 0x18 Protocol specific port (SAS transport) 0x19 General statistics and performance 0x2f Informational exceptions 0x37 Seagate cache (vendor, disk) 0x3e Seagate factory (vendor, disk) In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic (sg) device. In the 2.6 series block devices (e.g. SCSI disks and DVD drives) can also be specified. For exam- ple "sg_logs -a /dev/sda" will work in the 2.6 series ker- nels. EXIT STATUS The exit status of sg_logs is 0 when it is successful. Oth- erwise see the sg3_utils(8) man page. OLDER COMMAND LINE OPTIONS The options in this section were the only ones available prior to sg3_utils version 1.23 . In sg3_utils version 1.23 and later these older options can be selected by either set- ting the SG3_UTILS_OLD_OPTS environment variable or using '--old' (or '-O) as the first option. Options with arguments or with two or more letters can have an extra '-' prepended. For example: both '-pcb' and '--pcb' are acceptable. -a outputs all the log pages supported by the device. Equivalent to --all in the main description. -A outputs all the log pages and subpages supported by the device. Equivalent to '--all --all' in the main description. -c=PC Equivalent to --control=PC in the main description. -h suppresses decoding of known log sense pages and prints out the response in hex instead. -H same action as '-h' in this section and equivalent to sg3_utils-1.24 Last change: April 2007 5 SG3_UTILS SG_LOGS(8) --hex in the main description. -l lists the names of all logs sense pages supported by this device. Equivalent to --list in the main descrip- tion. -L lists the names of all logs sense pages and subpages supported by this device. Equivalent to '--list --list' in the main description. -m=LEN request only LEN bytes of response data. Default is 0 which is interpreted as all that is available. LEN is decimal unless it has a leading '0x' or trailing 'h'. Equivalent to --maxlen=LEN in the main description. -n Equivalent to --name in the main description. -N switch to the newer style options. -p=PG[,SPG] PG is the log page code to access. Should be a hexade- cimal number between 0 and 3f inclusive. If given SPG is the log subpage code. SPG should be a hexadecimal number between 0 and ff inclusive. The subpage code of 'ff' can be thought of as a wildcard. -paramp=PP PP is the parameter pointer value (in hex) to place in command. Should be a number between 0 and ffff inclusive. -pcb show Parameter Control Byte settings (only relevant when log parameters being output in ASCII). -ppc sets the Parameter Pointer Control (PPC) bit. Default is 0 (i.e. cleared). -r use SCSI LOG SELECT command (PCR bit set) to reset the all log pages (or the given page). Equivalent to --reset in the main description. -select use a LOG SELECT command. Equivalent to --select in the main description. -sp sets the Saving Parameters (SP) bit. Default is 0 (i.e. cleared). Equivalent to --sp in the main description. -t outputs the temperature. Equivalent to --temperature in the main description. sg3_utils-1.24 Last change: April 2007 6 SG3_UTILS SG_LOGS(8) -T outputs the transport ('Protocol specific port') log page. Equivalent to --transport in the main descrip- tion. -v increase level of verbosity. -V print out version string then exit. -? output usage message then exit. AUTHOR Written by Doug Gilbert REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2002-2007 Douglas Gilbert This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO smartctl(smartmontools), sg_senddiag(8) sg3_utils-1.24 Last change: April 2007 7 SG3_UTILS SG_LUNS(8) NAME sg_luns - send the SCSI REPORT LUNS command SYNOPSIS sg_luns [--decode] [--help] [--hex] [--quiet] [--raw] [--select=SR] [--verbose] [--version] DEVICE DESCRIPTION Send the SCSI REPORT LUNS command to the DEVICE and outputs the response. In the SPC-3 SCSI standard support for this command is mandatory. OPTIONS Arguments to long options are mandatory for short options as well. -d, --decode decode logical unit numbers into their hierarchical parts. Interprets luns as described in SAM-3 when the HiSup bit is set in a standard INQUIRY's response. -h, --help output the usage message then exit. -H, --hex output response to this command in ASCII hex. -q, --quiet output ASCII hex rendering of each report lun, one per line. -r, --raw output response in binary (to stdout). -s, --select=SR this option sets the 'select report' field (SR) in the SCSI REPORT LUNS command. The default value is 0. When 0 is given (or this option is not specified) then the DEVICE should yield a list of luns addressable via this "I_T nexus" that use the following lun addressing methods: logical unit addressing, peripheral device addressing and flat space addressing. When 1 is given the DEVICE should yield a list of only "well known" logical units addressable via this "I_T" nexus. When 2 is given the DEVICE should yield all luns addressable via this "I_T" nexus. To simplify, for the I_T nexus associated with the DEVICE, the meanings of the SR values are: 0 : all luns excluding well known logical units 1 : well known logical units 2 : all luns Values greater than 2 are reserved (at SPC-4 (rev 8)). sg3_utils-1.24 Last change: March 2007 1 SG3_UTILS SG_LUNS(8) -v, --verbose increase the level of verbosity, (i.e. debug output). -V, --version print the version string and then exit. EXIT STATUS The exit status of sg_luns is 0 when it is successful. Oth- erwise see the sg3_utils(8) man page. AUTHORS Written by Douglas Gilbert. REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2004-2007 Douglas Gilbert This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_inq(8) sg3_utils-1.24 Last change: March 2007 2 SG3_UTILS SG_MODES(8) NAME sg_modes - reads mode pages with SCSI MODE SENSE command SYNOPSIS sg_modes [--all] [--control=PC] [--dbd] [--dbout] [--exam- ine] [--flexible] [--help] [--hex] [--list] [--llbaa] [--page=PG[,SPG]] [--raw] [-R] [--six] [--verbose] [--ver- sion] [DEVICE] sg_modes [-6] [-a] [-A] [-c=PC] [-d] [-D] [-e] [-f] [-h] [-H] [-l] [-L] [-p=PG[,SPG]] [-r] [-subp=SPG] [-v] [-V] [-?] [DEVICE] DESCRIPTION This utility sends a MODE SENSE SCSI command to the DEVICE and outputs the response. There is a 6 byte and 10 byte (cdb) variant of the MODE SENSE command, this utility defaults to the 10 byte variant. This utility decodes mode page headers and block descriptors but outputs the contents of each mode page in hex. It also has no facility to change the mode page contents or block descriptor data. Mode page contents are decoded and can be changed by the sdparm utility. This utility supports two command line syntaxes, the pre- ferred one is shown first in the synopsis and explained in this section. A later section on the old command line syntax outlines the second group of options. If no page is given (and --list is not selected) then --all is assumed. The --all option requests all mode pages (but not subpages) in a single response. OPTIONS Arguments to long options are mandatory for short options as well. -a, --all output all the mode pages reported by the DEVICE. This is what the page code 63 (0x3f) is defined to do. When used once, mode subpages are not fetched. When used twice (e.g. '-aa'), all mode pages and subpages are requested which is equivalent to '--page=63,255'. -c, --control=PC PC is the page control value. Up to four different ver- sions of each page are held by the device: 0 : current values (i.e. those active at present) 1 : changeable values 2 : default values (i.e. the manufacturer's settings) 3 : saved values sg3_utils-1.24 Last change: February 2007 1 SG3_UTILS SG_MODES(8) The changeable values are bit masks showing which fields could be changed with a MODE SELECT. The saved values will be re-instated the next time the device is power cycled or reset. If this option is not given then current values [0] are assumed. -d, --dbd disable block descriptors. By default, block descrip- tors (usually one (for disks) or none) are returned in a MODE SENSE response. This option sets the "disable block descriptors" (DBD) bit in the cdb which instructs the device not to return any block descriptors in its response. Older devices may not support this setting and may return an "illegal request" sense key; alterna- tively they may ignore it. Oddly the Reduced Block Com- mand set (RBC) requires this bit set. -D, --dbout disable outputting block descriptors. Irrespective of whether block descriptors are present in the response or not, they are not output. -e, --examine examine each mode page in the range 0 through to 62 (inclusive). If some response is given then print out the mode page name or number (in hex) if the name is not known. -f, --flexible Some devices, bridges and/or drivers attempt crude translations between MODE SENSE 6 and 10 byte commands without correcting the response. This will cause the response to be mis-interpreted (usually with an error saying the response is malformed). With this option, the length of the response is checked, and if it looks wrong, the response is then decoded as if the other mode sense (cdb length) was sent. -h, --help print out the usage message then exit. -H, --hex The default action is to decode known mode page numbers (and subpage numbers) into text. When this option is used once, the response is output in hexadecimal. When this option is used twice, mode page numbers and page control values are output in hex. -l, --list lists all common page and subpage codes and their names that are found in the command set that matches the peripheral type of the given DEVICE. If no DEVICE and sg3_utils-1.24 Last change: February 2007 2 SG3_UTILS SG_MODES(8) no --page=PG is given then the common page and subpage codes and their names are listed for SBC (e.g. a disk). If no DEVICE is given and a --page=PG is given then the common page and subpage codes and their names are listed for the command set whose peripheral device type matches the value given to PG. For example 'sg_mode --list --page=1' lists the command mode pages and sub- pages for tape devices. Additionally if a sub_page_code is given then it is interpreted as a transport identif- ier and command transport specific mode page codes and their names are listed following the main mode page list. Other options are ignored. -L, --llbaa set the Long LBA Accepted (LLBAA) bit in the MODE SENSE (10) cdb. This bit is not defined in the MODE SENSE (6) cdb so setting the '-L' and '--six' options is reported as an error. When set the DEVICE may respond with 16 byte block descriptors as indicated by the 'LongLBA' field in the response. In most cases setting this option is not needed. -O, --old switch to older style options. -p, --page=PG page code to fetch. The PG is assumed to be a decimal value unless prefixed by '0x' or has a trailing 'h'. It should be a value between 0 and 63 (inclusive). When not given and a default is required then a value of 63 (0x3f), which fetches all mode pages, is used. -p, --page=PG,SPG page code and subpage code values to fetch. Both argu- ments are assumed to be decimal unless flagged as hexa- decimal. The page code should be between 0 and 63 inclusive. The subpage code should be between 0 and 255 inclusive. The default value for the subpage code is 0. -r, --raw output the response in binary to stdout. Error messages and warnings, if any, are sent to stderr. When this option is used twice (e.g. '-rr') then has the same action as '-R' -R output the selected mode page to stdout a byte per line. Each line contains two hexadecimal digits (e.g. "3e"). Useful as input (after editing) to the sg_wr_mode(8) utility. -6, --six by default this utility sends a 10 byte MODE SENSE sg3_utils-1.24 Last change: February 2007 3 SG3_UTILS SG_MODES(8) command to the DEVICE. However some SCSI devices only support 6 byte MODE SENSE commands (e.g. SCSI-2 tape drives). This parameter forces the use of 6 byte MODE SENSE commands. -v, --verbose increase level of verbosity. Can be used multiple times. -V, --version print out version string then exit. NOTES If the normal sg_modes utility fails with "illegal command operation code" then try the '--six' (or '-6') option. This utility performs a SCSI INQUIRY command to determine the peripheral type of the device (e.g. 0 -> Direct Access Device (disk)) prior to sending a MODE SENSE command. This helps in decoding the block descriptor and mode pages. In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic (sg) device. In the 2.6 series block devices (e.g. SCSI disks and DVD drives) can also be specified. For exam- ple "sg_modes -a /dev/sda" will work in the 2.6 series ker- nels. EXIT STATUS The exit status of sg_modes is 0 when it is successful. Oth- erwise see the sg3_utils(8) man page. OLDER COMMAND LINE OPTIONS The options in this section were the only ones available prior to sg3_utils version 1.23 . In sg3_utils version 1.23 and later these older options can be selected by either set- ting the SG3_UTILS_OLD_OPTS environment variable or using '--old' (or '-O) as the first option. -6 by default this utility sends a 10 byte MODE SENSE com- mand to the DEVICE. This parameter forces the use of 6 byte MODE SENSE commands. See --six in the main description. -a see --all in the main description. -A output all the mode pages and subpages supported by the DEVICE. Same as '--all --all' in the new syntax. -c=PC PC is the page control value. See --control=PC in the main description. sg3_utils-1.24 Last change: February 2007 4 SG3_UTILS SG_MODES(8) -d see --dbd in the main description. -D see --dbout in the main description. -e see --examine in the main description. -f see --flexible in the main description. -h The default action is to decode known mode page numbers (and subpage numbers) into text. With this option mode page numbers (and subpage numbers) are output in hexa- decimal. -H same action as the '-h' option. -l see --list in the main description. -L see --llbaa in the main description. -N switch to the newer style options. -p=PG PG is page code to fetch. Should be a hexadecimal number between 0 and 3f inclusive (0 to 63 decimal). The default value when required is 3f (fetch all mode pages). -p=PG,SPG page code and subpage code values to fetch. The page code should be a hexadecimal number between 0 and 3f inclusive. The subpage code should be a hexadecimal number between 0 and ff inclusive. The default value for the subpage code is 0. -r output the selected mode page to stdout a byte per line. Each line contains two hexadecimal digits (e.g. "3e"). Useful as input (after editing) to the sg_wr_mode(8) utility. -subp=SPG sub page code to fetch. Should be a hexadecimal number between 0 and 0xff inclusive. The default value is 0. -v increase verbosity of output. -V print out version string then exit. -? output usage message then exit. Ignore all other param- eters. AUTHOR Written by Doug Gilbert sg3_utils-1.24 Last change: February 2007 5 SG3_UTILS SG_MODES(8) REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2000-2007 Douglas Gilbert This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sdparm(8), sg_wr_mode(8), sginfo(8), sgmode(scsirastools), scsiinfo(net), scu(net), seatools(seagate) All these utilities offer some facility to change mode page (or block descriptor) parameters. sg3_utils-1.24 Last change: February 2007 6 SG3_UTILS SG_OPCODES(8) NAME sg_opcodes - reports information on supported SCSI commands or task management functions SYNOPSIS sg_opcodes [--alpha] [--help] [--hex] [--opcode=OP] [--raw] [--rctd] [--sa=SA] [--tmf] [--unsorted] [--verbose] [--ver- sion] DEVICE sg_opcodes [-a] [-o=OP] [-R] [-s=SA] [-t] [-u] [-v] [-V] [-?] DEVICE DESCRIPTION This utility sends a SCSI REPORT SUPPORTED OPERATION CODES or a REPORT SUPPORTED TASK MANAGEMENT FUNCTIONS command to the DEVICE and then outputs the response. The default action is to report supported operation codes. In this mode it will either list all supported commands or give detailed informa- tion on a specific command identified by the --opcode=OP option (perhaps with additional information from the --sa=SA option). The name of a SCSI command depends on its peripheral device type (e.g. a disk). The REPORT SUPPORTED OPERATION CODES and REPORT SUPPORTED TASK MANAGEMENT FUNCTIONS commands are not supported in the MMC command set for CD and DVD devices. This utility does an INQUIRY to obtain the peripheral device type and prints out the vendor, product and revision strings. A similar facility to query supported operation codes previ- ously was available via the CmdDt bit in the SCSI INQUIRY command (see sg_inq(8)). However that facility was made obsolete and replaced by the REPORT SUPPORTED OPERATION CODES command in SPC-3 (revision 4) during February 2002. This utility supports two command line syntaxes, the pre- ferred one is shown first in the synopsis and explained in this section. A later section on the old command line syntax outlines the second group of options. OPTIONS Arguments to long options are mandatory for short options as well. -a, --alpha when all supported commands are being listed there is no requirement for the device server (i.e. the DEVICE) to sort the list of commands. When this option is given the list of supported commands is sorted by name (alphabetically). When this option and the --unsorted option are both _not_ given then the list of supported sg3_utils-1.23 Last change: January 2007 1 SG3_UTILS SG_OPCODES(8) commands is sorted numerically (first by operation code and then by service action). -h, --help outputs the usage message summarizing command line options then exits. Ignores DEVICE if given. -H, --hex outputs the response in ASCII hexadecimal to stdout. -O, --old switch to older style options. -o, --opcode=OP the DEVICE will be queried for the given operation code ( i.e. the OP value) which is the first byte of a SCSI command. OP is decimal unless prefixed by "0x" or it has a trailing "h". OP should be in the range 0 to 255 (0xff) inclusive. When this option is not given then all available SCSI commands supported by the DEVICE are listed. -r, --raw output the response in binary to stdout. Error messages and warnings, if any, are sent to stderr. -R, --rctd set report command timeout descriptor (RCTD) bit in the cdb. The response may or may not contain command timeout descriptors. If available they are output. If supported there are two values: a nominal command timeout and a recommended command timeout. Both have units of seconds. A value of zero means that no timeout is indicated and this is shown in the corresponding decoded output as "-". -s, --sa=SA the DEVICE will be queried for a command with the given service action (i.e. the SA value). Used in conjunction with the --opcode=OP option. If this option is not given, --opcode=OP is given and the command in question does have a service action then a value of 0 will be assumed. SA is decimal and expected to be in the range 0 to 65535 (0xffff) inclusive. -t, --tmf list supported task management functions. This is done with the SCSI REPORT SUPPORTED TASK MANAGEMENT FUNC- TIONS command. When this option is chosen the --alpha, --opcode=OP, --rctd, --sa=SA and --unsorted options are ignored. sg3_utils-1.23 Last change: January 2007 2 SG3_UTILS SG_OPCODES(8) -u, --unsorted when all supported commands are being listed there is no requirement for the device server (i.e. the DEVICE) to sort the list of commands. When this option is given the list of supported commands is in the order given by the DEVICE. When this option is not given the supported commands are sorted numerically (first by operation code and then by service action). -v, --verbose increase level of verbosity. Can be used multiple times. -V, --version print out version string then exit. NOTES As of SPC-4 revision 7a the recognized task management func- tions are: abort set, abort task set, clear ACA, clear task set, I_T nexus reset, logical unit reset, query task, target reset and wakeup. In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic (sg) device. In the 2.6 series block devices (e.g. SCSI disks and DVD drives) can also be specified. For exam- ple "sg_opcodes /dev/sda" will work in the 2.6 series ker- nels. EXIT STATUS The exit status of sg_opcodes is 0 when it is successful. Otherwise see the sg3_utils(8) man page. OLDER COMMAND LINE OPTIONS The options in this section were the only ones available prior to sg3_utils version 1.23 . In sg3_utils version 1.23 and later these older options can be selected by either set- ting the SG3_UTILS_OLD_OPTS environment variable or using '--old' (or '-O) as the first option. -a sort command alphabetically. Equivalent to --alpha in main description. -N switch to the newer style options. -o=OP the DEVICE will be queried for the given operation code (i.e. OP) which is the first byte of a SCSI command. OP is hexadecimal and expected to be in the range 0 to ff inclusive. When this option is not given then all available SCSI commands supported by the DEVICE are listed. sg3_utils-1.23 Last change: January 2007 3 SG3_UTILS SG_OPCODES(8) -R set the report command timeout descriptor (RCTD) bit in cdb. Equivalent to --rctd in main description. -s=SA the DEVICE will be queried for a command with the given service action (i.e. SA). Used in conjunction with the -o=OP option. If this option is not given, -o=OP is given and the command in question does have a service action then a value of 0 will be assumed. SA is hexa- decimal and expected to be in the range 0 to ffff inclusive. -t list supported task management functions. Equivalent to --tmf in the main description. -u output all supported commands in the order given by DEVICE. Equivalent to --unsorted in main description. -v increase level of verbosity. Can be used multiple times. -V print out version string then exit. -? output usage message. Ignore all other parameters. AUTHOR Written by Doug Gilbert REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2004-2007 Douglas Gilbert This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_inq(sg3_utils) sg3_utils-1.23 Last change: January 2007 4 SG3_UTILS SG_PERSIST(8) NAME sg_persist - sends a SCSI PERSISTENT RESERVE (IN or OUT) command to manipulate registrations and reservations SYNOPSIS sg_persist [OPTIONS] DEVICE sg_persist [OPTIONS] --device=DEVICE sg_persist --help | --version DESCRIPTION This utility allows Persistent reservations and registra- tions to be queried and changed. Persistent reservations and registrations are queried by sub-commands (called "service actions" in SPC-4) of the SCSI PERSISTENT RESERVE IN (PRIN) command. Persistent reservations and registrations are changed by sub-commands of the SCSI PERSISTENT RESERVE OUT (PROUT) command. There is a two stage process to obtain a persistent reserva- tion. First an application (an I_T nexus in standard's jar- gon) must register a reservation key. If that is accepted (and it should be unless some other I_T nexus has registered that key) then the application can try and reserve the dev- ice. The reserve operation must specify the reservation key and a "type" (see the --prout-type=TYPE option). It is relatively safe to query the state of Persistent reservations and registrations. With no options this utility defaults to the READ KEYS sub-command of the PRIN command. Other PRIN sub-commands are READ RESERVATION, REPORT CAPA- BILITIES and READ FULL STATUS. Before trying to change Persistent reservations and regis- trations users should be aware of what they are doing. The relevant sections of the SCSI Primary Commands document (i.e. SPC-4 whose most recent draft is revision 9 dated 17th February 2007) are sections 5.6 (titled "Reservation"), 6.13 (for the PRIN command) and 6.14 (for the PROUT command). To safeguard against accidental use, the --out option must be given when a PROUT sub-command (e.g. --register) is used. The older SCSI RESERVE and RELEASE commands (both 6 and 10 byte variants) are not supported by this utility. In SPC-3, RESERVE and RELEASE are deprecated, replaced by Persistent Reservations. RESERVE and RELEASE have been removed from SPC-4 and Annex B is provided showing how to convert to per- sistent reservation commands. See a utility called 'scsires' for support of the SCSI RESERVE and RELEASE commands. sg3_utils-1.25 Last change: October 2007 1 SG3_UTILS SG_PERSIST(8) The DEVICE is required by all variants of this utility apart from --help. The DEVICE can be given either as an argument (typically but not necessarily the last one) or via the --device=DEVICE option. SPC-4 does not use the term "sub-command". It uses the term "service action" for this and for part of a field's name in the parameter block associated with the PROUT command (i.e. "service action reservation key"). To lessen the potential confusion the term "sub-command" has been introduced. OPTIONS Arguments to long options are mandatory for short options as well. The following options are sorted in alphabetical order, based on their long option name. -C, --clear Clear is a sub-command of the PROUT command. It releases the persistent reservation (if any) and clears all registrations from the device. It is required to supply a reservation key that is registered for this I_T_L nexus (identified by --param-rk=RK). -d, --device=DEVICE DEVICE to send SCSI commands to. The DEVICE can either be provided via this option or via a freestanding argu- ment. For example, these two: 'sg_persist --device=/dev/sg2' and 'sg_persist /dev/sg2' are equivalent. -h, --help output a usage message. -H, --hex the response to a valid PRIN sub-command will be output in hexadecimal. By default (i.e. without this option) if the PRIN sub-command is recognised then the response will be decoded as per SPC-4. -i, --in specify that a SCSI PERSISTENT RESERVE IN command is required. This is the default. -n, --no-inquiry the default action is to do a standard SCSI INQUIRY command and output make, product and revision strings plus the peripheral device type prior to executing a PRIN or PROUT command. With this option the INQUIRY command is skipped. -o, --out specify that a SCSI PERSISTENT RESERVE OUT command is sg3_utils-1.25 Last change: October 2007 2 SG3_UTILS SG_PERSIST(8) required. -Y, --param-alltgpt set the 'all target ports' (ALL_TG_PT) flag in the parameter block of the PROUT command. Only relevant for 'register' and 'register and ignore existing key' sub-commands. -Z, --param-aptpl set the 'activate persist through power loss' (APTPL) flag in the parameter block of the PROUT command. Relevant for 'register', 'register and ignore existing key' and 'register and move' sub-commands. -K, --param-rk=RK specify the reservation key found in the parameter block of the PROUT command. RK is assumed to be hex (up to 8 bytes long). Default value is 0. This option is needed by most PROUT sub-commands. -S, --param-sark=SARK specify the service action reservation key found in the parameter block of the PROUT command. SARK is assumed to be hex (up to 8 bytes long). Default value is 0. This option is needed by some PROUT sub-commands. -P, --preempt Preempt is a sub-command of the PROUT command. Preempts the existing persistent reservation (identified by --param-sark=SARK) with the registration key that is registered for this I_T_L nexus (identified by --param-rk=RK). The associated --prout-type=TYPE option needs to match the type of the reservation. -A, --preempt-abort Preempt and Abort is a sub-command of the PROUT com- mand. Preempts the existing persistent reservation (identified by --param-sark=SARK) with the registration key that is registered for this I_T_L nexus (identified by --param-rk=RK). The associated --prout-type=TYPE option needs to match the type of the reservation. ACA and other pending tasks are aborted. -T, --prout-type=TYPE specify the PROUT command's 'type' argument. Required by the 'register-move', 'reserve', 'release' and 'preempt (and abort)' sub-commands. Valid TYPE values: 1-> write exclusive, 3-> exclusive access, 5-> write exclusive - registrants only, 6-> exclusive access - registrants only, 7-> write exclusive - all regis- trants, 8-> exclusive access - all registrants. Default value is 0 (which is an invalid type). Each "persistent sg3_utils-1.25 Last change: October 2007 3 SG3_UTILS SG_PERSIST(8) reservation type" is explained in more detail in a sub- section of that name in the read reservation section of the PRIN command (section 6.13.3.4 of SPC-4 revision 9). -s, --read-full-status Read Full Status is a sub-command of the PRIN command. For each registration with the given SCSI device, it lists the reservation key and associated information. TransportIDs, if supplied in the response, are decoded. -k, --read-keys Read Keys is a sub-command of the PRIN command. Lists all the reservation keys registered (i.e. registra- tions) with the given SCSI device. This is the default sub-command for the SCSI PRIN command. -r, --read-reservation Read Reservation is a sub-command of the PRIN command. List information about the current holder of the reser- vation on the DEVICE. If there is no current reserva- tion this will be noted. Information about the current holder of the reservation includes its reservation key, scope and type. -s, --read-status same as --read-full-status. -G, --register Register is a sub-command of the PROUT command. It has 3 different actions depending on associated parameters. a) add a new registration with '--param-rk=0' and '--param-sark='; b) Change an existing regis- tration with '--param-rk=' and '--param-sark='; or c) Delete an existing registration with '--param-rk=' and '--param-sark=0'. -I, --register-ignore Register and Ignore Existing Key is a sub-command of the PROUT command. Similar to --register except that when changing a reservation key the old key is not specified. The '--prout-sark=' option should also be given. -M, --register-move register (another initiator) and move (the reservation held by the current initiator to that other initiator) is a sub-command of the PROUT command. It requires the transportID of the other initiator. [The standard uses the term I_T nexus but the point to stress is that there are two initiators (the one sending this command sg3_utils-1.25 Last change: October 2007 4 SG3_UTILS SG_PERSIST(8) and another one) but only one logical unit.] The --prout-type=TYPE and --param-rk=RK options need to match that of the existing reservation while --param-sark=SARK option specifies the reservation key of the new (i.e. destination) registration. -Q, --relative-target-port=RTPI relative target port identifier that reservation is to be moved to by PROUT 'register and move' sub-command. RTPI is assumed to be hex in the range 0 to ffff inclusive. Defaults to 0 . -L, --release Release is a sub-command of the PROUT command. It releases the current persistent reservation. The --prout-type=TYPE and --param-rk=RK options, matching the reservation, must also be specified. -c, --report-capabilities Report Capabilities is a sub-command of the PRIN com- mand. It lists information about the aspects of per- sistent reservations that the DEVICE supports. -R, --reserve Reserve is a sub-command of the PROUT command. It creates a new persistent reservation (if permitted). The --prout-type=TYPE and --param-rk=RK options must also be specified. -X, --transport-id=H,H... a transportID is required for the PROUT 'register and move' sub-command and is optional for the PROUT 'regis- ter' and 'register and ignore existing key' sub-commands. The latter two sub-commands can take mul- tiple transportIDs in a list but only one is supported with this option variant (use the following option variant that reads stdin if multiple transportIDs are required). H,H... is a comma separated list of hex bytes which represent the transportID. The list of hex numbers will be padded out with zeros to 24 bytes which is the minimum length of a transportID. A transportID longer than 24 bytes (e.g. for iSCSI) is padded with zeros so its length is a multiple of 4. -X, --transport-id=- a transportID is required for the PROUT 'register and move' sub-command and is optional for the PROUT 'regis- ter' and 'register and ignore existing key' sub-commands. The latter two sub-commands can take mul- tiple transportIDs in a list. The argument is '-' which indicates stdin should be read for the transportID(s). Empty lines are ignored. Everything from and including sg3_utils-1.25 Last change: October 2007 5 SG3_UTILS SG_PERSIST(8) a "#" on a line is ignored. Leading spaces and tabs are ignored. All numbers are assumed to be hexadecimal and can be separated by space, comma or tab. There can be one transportID per line. TranportIDs will be padded out with zeros to 24 bytes which is the minimum length of a transportID. A transportID longer than 24 bytes (e.g. for iSCSI) is padded with zeros so its length is a multiple of 4. -U, --unreg optional when the PROUT register and move sub-command is invoked. If given it will unregister the current initiator (I_T nexus) after the other initiator has been registered and the reservation moved to it. When not given the initiator (I_T nexus) that sent the PROUT command remains registered. -v, --verbose print out cdb of issued commands prior to execution. If used twice prints out the parameter block associated with the PROUT command prior to its execution as well. If used thrice decodes given transportID(s) as well. To see the response to a PRIN command in low level form use the --hex option. -V, --version print out version string. Ignore all other parameters. -? output usage message. Ignore all other parameters. NOTES In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic (sg) device. In the 2.6 series any SCSI device name (e.g. /dev/sdc, /dev/st1m or /dev/sg3) can be specified. For example "sg_persist --read-keys /dev/sda" will work in the 2.6 series kernels. The only scope for PROUT commands supported in the current draft of SPC-4 is "LU_SCOPE". Hence there seems to be no point in offering an option to set scope to another value. Most errors with the PROUT sub-commands (e.g. missing or mismatched --prout-type=TYPE) will result in a RESERVATION CONFLICT status. This can be a bit confusing when you know there is only one (active) initiator: the "conflict" is with the SPC standard, not another initiator. TransportIDs are defined in SPC-4 and their structures vary depending on the underlying transport. EXAMPLES sg3_utils-1.25 Last change: October 2007 6 SG3_UTILS SG_PERSIST(8) Due to defaults the simplest example executes the 'read keys' sub-command of the PRIN command: sg_persist /dev/sda This is the same as the following (long-winded) command: sg_persist --in --read-keys --device=/dev/sda To read the current reservation either the '--read-reservation' form or the shorter '-r' can be used: sg_persist -r /dev/sda To register the new reservation key 0x123abc the following could be used: sg_persist --out --register --param-sark=123abc /dev/sda Given the above registration succeeds, to reserve the DEVICE (with type 'write exclusive') the following could be used: sg_persist --out --reserve --param-rk=123abc --prout-type=1 /dev/sda To release the reservation the following can be given (note that the --param-rk and --prout-type arguments must match those of the reservation): sg_persist --out --release --param-rk=123abc --prout-type=1 /dev/sda Finally to unregister a reservation key (and not effect other registrations which is what '--clear' would do) the command is a little surprising: sg_persist --out --register --param-rk=123abc /dev/sda Now have a close look at the difference between the register and unregister examples above. An example file that is suitably formatted to pass transpor- tIDs via the '--transport-id=-' option can be found in the examples sub-directory of the sg3_utils package. That file is called 'transport_ids.txt'. EXIT STATUS The exit status of sg_persist is 0 when it is successful. Otherwise see the sg3_utils(8) man page. AUTHOR Written by Doug Gilbert sg3_utils-1.25 Last change: October 2007 7 SG3_UTILS SG_PERSIST(8) REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2004-2007 Douglas Gilbert This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO scsires(internet), examples/sg_persist_tst.sh(sg3_utils tar- ball) sg3_utils-1.25 Last change: October 2007 8 SG3_UTILS SG_PREVENT(8) NAME sg_prevent - sends a SCSI PREVENT ALLOW MEDIUM REMOVAL com- mand SYNOPSIS sg_prevent [--allow] [--help] [--prevent=PC] [--verbose] [--version] DEVICE DESCRIPTION Sends a SCSI PREVENT ALLOW MEDIUM REMOVAL command to DEVICE. The default action of this utility is to prevent the remov- ing or ejecting of the medium from a drive. This is done by ignoring the SCSI START STOP UNIT command (see sg_start) and ignoring the eject button on the drive when the user presses it. Drives that hold removable disks, tape cartridges or cd/dvd media typically implement this command. The defini- tion of the "prevent" codes for this command differ between disks and tapes (covered by SBC-3 and SSC-3) and cd/dvd drives (covered by MMC-5). The "prevent codes" described here are from MMC-5. OPTIONS Arguments to long options are mandatory for short options as well. -a, --allow allow medium removal. This is equivalent to setting to '--prevent=2'. Cannot be used with --prevent=PC option (i.e. either use no options (hence prevent removal), this option or --prevent=PC). -h, --help output the usage message then exit. -p, --prevent=PC where PC is a prevent code value. Defined values are: 0 allows removal, 1 prevents removal (default), 2 allows persistent removal while 3 prevents persistent removal. "Persistent" in this context means that the initiator (port) that successfully uses code 3 blocks other ini- tiators (ports) from allowing removal. A "persistent prevent" state can be cleared by the owner allowing persistent removal (code 2) or a power cycle (or any- thing that resets the device (lun)) or some special commands (e.g. various service actions of Persistent Reserve Out, see SPC-3). -v, --verbose increase the level of verbosity, (i.e. debug output). -V, --version print the version string and then exit. sg3_utils-1.23 Last change: January 2007 1 SG3_UTILS SG_PREVENT(8) EXIT STATUS The exit status of sg_prevent is 0 when it is successful. Otherwise see the sg3_utils(8) man page. AUTHORS Written by Douglas Gilbert. REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2004-2007 Douglas Gilbert This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_start(sg3_utils), sg_persist(sg3_utils) sg3_utils-1.23 Last change: January 2007 2 SG3_UTILS SG_RAW(8) NAME sg_raw - sends an arbitrary SCSI command (with an optional data phase) to a device SYNOPSIS sg_raw [OPTIONS] DEVICE CDB0 CDB1 ... DESCRIPTION This utility sends an arbitrary SCSI command (between 6 and 16 bytes) to the DEVICE. For the optional data phase, data can either be read from a file and sent to the DEVICE or received from the DEVICE and then displayed or written to a file. The SCSI command may be between 6 and 16 bytes long. Each command byte is specified in plain hex format (00..FF) without a prefix or suffix. See EXAMPLES section below. The commands pass through a generic SCSI interface which is implemented for several operating systems including Linux, FreeBSD and Windows. OPTIONS Arguments to long options are mandatory for short options as well. -b, --binary Dump data in binary form, even when writing to stdout. -h, --help Display usage information and exit. -i, --infile=IFILE Read data from IFILE instead of stdin. This option is ignored if --send is not specified. -k, --skip=LEN Skip the first LEN bytes of the input file or stream. This option is ignored if --send is not specified. -n, --nosense Don't display SCSI Sense information. -o, --outfile=OFILE Write data received from the DEVICE to OFILE. By default, data is dumped in hex format to stdout. This option is ignored if --request is not specified. -r, --request=RLEN Expect to receive up to RLEN bytes of data from the DEVICE. RLEN may be suffixed with 'k' to use kilobytes (1024 bytes) instead of bytes. This option and --send sg3_utils-1.24 Last change: April 2007 1 SG3_UTILS SG_RAW(8) are mutually exclusive. -s, --send=SLEN Read SLEN bytes of data, either from stdin or from a file, and send them to the DEVICE. This option and --request are mutually exclusive. -t, --timeout=SEC Wait up to SEC seconds for command completion (default: 20). Note that if a command times out the operating system may start by aborting the command and if that is unsuccessful it may attempt to reset the device. -v, --verbose Increase level of verbosity. Can be used multiple times. -V, --version Display version and license information and exit. EXAMPLES sg_raw /dev/scd0 1b 00 00 00 02 00 Eject the medium in CD drive /dev/scd0. sg_raw -r 1k /dev/sg0 12 00 00 00 60 00 Perform an INQUIRY on /dev/sg0 and dump the response data (up to 1024 bytes) to stdout. sg_raw -s 512 -i i512.bin /dev/sda 3b 02 00 00 00 00 00 02 00 00 Showing an example of writing 512 bytes to a sector on a disk is a little dangerous. Instead this example will read i512.bin (assumed to be 512 bytes long) and use the SCSI WRITE BUFFER command to send it to the "data" buffer (that is mode 2). This is a safe operation. sg_raw -r 512 -o o512.bin /dev/sda 3c 02 00 00 00 00 00 02 00 00 This will use the SCSI READ BUFFER command to read 512 bytes from the "data" buffer (i.e. mode 2) then write it to the o512.bin file. When used in conjunction with the previous example, if both commands work then 'cmp i512.bin o512.bin' should show a match. EXIT STATUS The exit status of sg_raw is 0 when it is successful. Other- wise see the sg3_utils(8) man page. AUTHOR Written by Ingo van Lil REPORTING BUGS Report bugs to . sg3_utils-1.24 Last change: April 2007 2 SG3_UTILS SG_RAW(8) COPYRIGHT Copyright O 2001-2007 Ingo van Lil This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_opcodes sg_vpd(sg3_utils), hdparm(hdparm), sgdiag(scsirastools) sg3_utils-1.24 Last change: April 2007 3 SG3_UTILS SG_RDAC(8) NAME sg_rdac - Display or Modify RDAC Redundant Controller Page SYNOPSIS sg_rdac [-a] [-f=LUN] [-v] [-V] DEVICE DESCRIPTION sg_rdac displays or modifies the RDAC controller settings via the Redundant Controller Page (0x2C). When modifying the settings it allows to transfer the ownership of individual drives to the controller the command was received on. OPTIONS -a Transfer all (visible) devices -f=LUN Transfer the device identified by LUN. This command will only work if the controller supports 'Dual Active Mode' (aka active/active mode). -v be verbose -V print version string then exit EXIT STATUS The exit status of sg_rdac is 0 when it is successful. Oth- erwise see the sg3_utils(8) man page. AUTHOR Written by Hannes Reinecke , based on sg_emc_trespass. REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2006-2007 Hannes Reinecke, Douglas Gilbert. This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. sg3_utils-1.23 Last change: January 2007 1 SG3_UTILS SG_READ_BUFFER(8) NAME sg_read_buffer - send a SCSI READ BUFFER command SYNOPSIS sg_read_buffer [--help] [--hex] [--id=ID] [--length=LEN] [--mode=MO] [--offset=OFF] [--raw] [--verbose] [--version] DEVICE DESCRIPTION Sends a SCSI READ BUFFER command to the DEVICE, and if there is a response either decodes it, prints it in hexadecimal or sends it in binary to stdout. If a response is received for a "descriptor" mode then, in the absence of --hex and --raw, it is decoded. Response for non-descriptor modes are output in hexadecimal unless the --raw option is given. OPTIONS Arguments to long options are mandatory for short options as well. -h, --help output the usage message then exit. If used multiple times also prints the mode names and their acronyms. -H, --hex output the response in hexadecimal. -i, --id=ID this option sets the buffer id field in the cdb. ID is a value between 0 (default) and 255 inclusive. -l, --length=LEN where LEN is the length, in bytes, that is placed in the "allocation length" field in the cdb. The default value is 4 (bytes). The device may respond with less bytes. -m, --mode=MO this option sets the mode field in the cdb. MO is a value between 0 (default) and 31 inclusive. Alterna- tively an abbreviation can be given. To list the available mode abbreviations given an invalid one (e.g. '--mode=xxx'). -o, --offset=OFF this option sets the buffer offset field in the cdb. OFF is a value between 0 (default) and 2**24-1 . It is a byte offset. -r, --raw if a response is received then it is sent in binary to stdout. sg3_utils-1.23 Last change: January 2007 1 SG3_UTILS SG_READ_BUFFER(8) -v, --verbose increase the level of verbosity, (i.e. debug output). -V, --version print the version string and then exit. NOTES All numbers given with options are assumed to be decimal. Alternatively numerical values can be given in hexadecimal preceded by either "0x" or "0X" (or has a trailing "h" or "H"). EXIT STATUS The exit status of sg_read_buffer is 0 when it is success- ful. Otherwise see the sg3_utils(8) man page. AUTHORS Written by Luben Tuikov and Douglas Gilbert. REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2006-2007 Luben Tuikov and Douglas Gilbert This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_write_buffer(sg3_utils) sg3_utils-1.23 Last change: January 2007 2 SG3_UTILS SG_READCAP(8) NAME sg_readcap - sends a SCSI READ CAPACITY command SYNOPSIS sg_readcap [--brief] [--help] [--hex] [--lba=LBA] [--long] [--pmi] [--raw] [--verbose] [--version] DEVICE sg_readcap [-16] [-b] [-h] [-H] [-lba=LBA] [-pmi] [-r] [-v] [-V] DEVICE DESCRIPTION The normal action of the SCSI READ CAPACITY command is to fetch the number of blocks (and block size) from the DEVICE. The SCSI READ CAPACITY command (both 10 and 16 byte cdbs) actually yield the block address of the last block and the block size. The number of blocks is thus one plus the block address of the last block (as blocks are counted origin zero (i.e. starting at block zero)). This is the source of many "off by one" errors. Device capacity is the product of the number of blocks by the block size. This utility outputs this figure in bytes, MiB (1048576 bytes per MiB) and GB (1000000000 bytes per GB). This utility supports two command line syntaxes, the pre- ferred one is shown first in the synopsis and explained in this section. A later section on the old command line syntax outlines the second group of options. OPTIONS Arguments to long options are mandatory for short options as well. -b, --brief outputs two hex numbers (prefixed with '0x' and space separated) to stdout. The first number is the maximum number of blocks on the device (which is one plus the lba of the last accessible block). The second number is the size of each block. If the operation fails then "0x0 0x0" is written to stdout. -h, --help print out the usage message then exit. -H, --hex output the response to the READ CAPACITY command (either the 10 or 16 byte cdb variant) in ASCII hexade- cimal on stdout. -L, --lba=LBA sg3_utils-1.23 Last change: January 2007 1 SG3_UTILS SG_READCAP(8) used in conjunction with --pmi option. This variant of READ CAPACITY will yield the last block address after LBA prior to a delay. For a disk, given a LBA it yields the highest numbered block on the same cylinder (i.e. before the heads need to move). LBA is assumed to be decimal unless prefixed by "0x" or it has a trailing "h". Defaults to 0. -l, --long Use the 16 byte cdb variant of the READ CAPACITY com- mand. The default action is to use the 10 byte cdb variant which limits the maximum block address to (2**32 - 2). When a 10 byte cdb READ CAPACITY command is used on a device whose size is too large then a last block address of 0xffffffff is returned (if the device complies with SBC-2). -O, --old switch to older style options. -p, --pmi partial medium indicator: for finding the next block address prior to some delay (e.g. head movement). In the absence of this option, the total number of blocks and the block size of the device are output. Used in conjunction with the --lba=LBA option. -r, --raw output response in binary to stdout. -v, --verbose increase level of verbosity. Can be used multiple times. -V, --version outputs version string then exits. NOTES If sg_readcap is called without the --long option then the 10 byte cdb version (i.e. READ CAPACITY (10)) is sent to the DEVICE. If the number of blocks in the response is reported as 0xffffffff (i.e. (2**32 - 1) ) and the --hex option has not been given, then READ CAPACITY (16) is called and its response is output. The read capacity(16) response shows additional information not found in the read capacity(10) response. This includes protection information and the number of logical blocks per physical block. So even though the media size may not exceed what READ CAPACITY(10) can show, it may still be useful to examine the response to READ CAPACITY(16). sg3_utils-1.23 Last change: January 2007 2 SG3_UTILS SG_READCAP(8) In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic (sg) device. In the 2.6 series block devices (e.g. SCSI disks and DVD drives) can also be specified. For exam- ple "sg_readcap /dev/sda" and "sg_readcap /dev/hdd" (if /dev/hdd is a ATAPI CD/DVD device) will work in the 2.6 series kernels. EXIT STATUS The exit status of sg_readcap is 0 when it is successful. Otherwise see the sg3_utils(8) man page. OLDER COMMAND LINE OPTIONS The options in this section were the only ones available prior to sg3_utils version 1.23 . In sg3_utils version 1.23 and later these older options can be selected by either set- ting the SG3_UTILS_OLD_OPTS environment variable or using '--old' (or '-O) as the first option. -16 Use the 16 byte cdb variant of the READ CAPACITY com- mand. Equivalent to --long in the main description. -b utility outputs two hex numbers (prefixed with '0x' and space separated) to stdout. The first number is the maximum number of blocks on the device (which is one plus the lba of the last accessible block). The second number is the size of each block. If the operation fails then "0x0 0x0" is written to stdout. Equivalent to --brief in the main description. -h output the usage message then exit. Giving the -? option also outputs the usage message then exits. -H output the response to the READ CAPACITY command (either the 10 or 16 byte cdb variant) in ASCII hexade- cimal on stdout. -lba=LBA used in conjunction with -pmi option. This variant of READ CAPACITY will yield the last block address after LBA prior to a delay. Equivalent to --lba=LBA in the main description. -N switch to the newer style options. -pmi partial medium indicator: for finding the next block address prior to some delay (e.g. head movement). In the absence of this switch, the total number of blocks and the block size of the device are output. Equivalent to --pmi in the main description. -r output response in binary (to stdout). sg3_utils-1.23 Last change: January 2007 3 SG3_UTILS SG_READCAP(8) -v verbose: print out cdb of issued commands prior to exe- cution. '-vv' and '-vvv' are also accepted yielding greater verbosity. -V outputs version string then exits. AUTHORS Written by Douglas Gilbert COPYRIGHT Copyright O 1999-2007 Douglas Gilbert This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_inq(sg3_utils) sg3_utils-1.23 Last change: January 2007 4 SG3_UTILS SG_READ_LONG(8) NAME sg_read_long - send a SCSI READ LONG command SYNOPSIS sg_read_long [--16] [--correct] [--help] [--lba=LBA] [--out=OF] [--pblock] [--verbose] [--version] [--xfer_len=BTL] DEVICE DESCRIPTION Send SCSI READ LONG command to DEVICE. The read buffer is output in hex and ASCII to stdout or placed in a file. Note that the data returned includes the logical block data (typ- ically 512 bytes for a disk) plus ECC information (whose format is proprietary) plus optionally other proprietary data. OPTIONS Arguments to long options are mandatory for short options as well. -S, --16 uses a SCSI READ LONG(16) command. The default action is to use a SCSI READ LONG(10) command. The READ LONG(10) command has a 32 bit field for the lba while READ LONG(16) has a 64 bit field. -c, --correct sets the 'CORRCT' bit in the SCSI READ LONG command. When set the data is corrected by the ECC before being transferred back to this utility. The default is to leave the 'CORRCT' bit clear in which case the data is not corrected. -h, --help output the usage message then exit. -l, --lba=LBA where LBA is the logical block address of the sector to read. Assumed to be in decimal unless prefixed with '0x' (or has a trailing 'h'). Defaults to lba 0. If the lba is larger than can fit in 32 bits then the --16 option should be used. -o, --out=OF instead of outputting ASCII hex to stdout, send it in binary to the file called OF. If '-' is given for OF then the (binary) output is sent to stdout. Note that all informative and error output is sent to stderr. -p, --pblock sets the 'PBLOCK' bit in the SCSI READ LONG command. When set the physical block (plus ECC data) containing sg3_utils-1.23 Last change: January 2007 1 SG3_UTILS SG_READ_LONG(8) the requested logical block address is read. The default is to leave the 'PBLOCK' bit clear in which case the logical block (plus any ECC data) is read. -v, --verbose increase the level of verbosity, (i.e. debug output). -V, --version print the version string and then exit. -x, --xfer_len=BTL where BTL is the byte transfer length (default to 520). If the given value (or the default) does not match the "long" block size of the device, the appropriate BTL is deduced from the error response and printed (to stderr). The idea is that the user will retry this utility with the correct transfer length. NOTES If a defective block is found and its contents, if any, has been retrieved then "sg_reassign" could be used to map out the defective block. Associated with such an action the number of elements in the "grown" defect list could be moni- tored (with "sg_reassign --grown") as the disk could be nearing the end of its useful lifetime. The LBA and BTL (transfer length) arguments may be followed by the following multiplicative suffixes: c C *1; w W *2; b B *512; k K KiB *1,024; KB *1,000; m M MiB *1,048,576; MB *1,000,000; g G GiB *1,073,741,824; and GB *1,000,000,000 . Also a suffix of the form "x" multiplies the leading number by . Alternatively numerical values can be given in hexadecimal preceded by either "0x" or "0X" (or with a trailing "h" or "H"). When hex numbers are given, multipliers cannot be used. As a data point, Fujitsu uses a 54 byte ECC (per block) which is capable of correcting up to a single burst error or 216 bits "on the fly". [Information obtained from MAV20xxrc product manual.] EXIT STATUS The exit status of sg_read_long is 0 when it is successful. Otherwise see the sg3_utils(8) man page. AUTHORS Written by Douglas Gilbert. REPORTING BUGS Report bugs to . sg3_utils-1.23 Last change: January 2007 2 SG3_UTILS SG_READ_LONG(8) COPYRIGHT Copyright O 2004-2007 Douglas Gilbert This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_reassign, sg_write_long, sg_dd sg3_utils-1.23 Last change: January 2007 3 SG3_UTILS SG_REASSIGN(8) NAME sg_reassign - sends a SCSI REASSIGN BLOCKS command SYNOPSIS sg_reassign [--address=A,A...] [--dummy] [--eight=0|1] [--grown] [--help] [--longlist=0|1] [--primary] [--verbose] [--version] DEVICE DESCRIPTION Send a SCSI REASSIGN BLOCKS command to DEVICE. Alternatively this utility can find the number of element in a "grown" or "primary" defect list with a SCSI READ DEFECT DATA (10) com- mand. These SCSI commands are defined in SBC-2 for direct access devices (e.g. a disk). Reassign blocks is designed to change the physical location of a logical block that is known or suspected to be defective to another area on the media. Disks are typically formatted with blocks held in reserve for this situation. If neither the --grown nor --primary option is supplied then one or more addresses need to be given. If the address (or all of the addresses) fit into 4 bytes and '--eight=1' is not given then the parameter block passed to DEVICE is made up of 4 byte logical block addresses. If any of the addresses need more than 4 bytes to represent (i.e. >= 2**32) or '--eight=1' is given then the parameter block passed to DEVICE is made up of 8 byte logical block addresses. OPTIONS Arguments to long options are mandatory for short options as well. -a, --address=A,A... where A,A... is a string of comma separated numbers. Each number is interpreted as decimal unless prefixed by '0x' or '0X' (or it has a trailing 'h' or 'H'). If multiple logical block addresses are given they must be separated by a comma. At least one address must be given. -a, --address=- reads one or more logical block addresses from stdin. These may be comma, space, tab or linefeed (newline) separated. If a line contains "#" then the remaining characters on that line are ignored. Otherwise each non separator sequence of characters should resolve to a decimal number unless prefixed by '0x' or '0X' (or has a trailing 'h'). At least one address must be given. -d, --dummy prepare for but do not execute the SCSI REASSIGN BLOCKS sg3_utils-1.23 Last change: January 2007 1 SG3_UTILS SG_REASSIGN(8) command. Since the REASSIGN BLOCKS command is essen- tially irreversible, paranoid users may wish to check the invocation of this utility before reassigning defective blocks on a disk. Useful with '-vv' for those who wish to view the parameter block that will accom- pany the command. -e, --eight=0 | 1 when value is 1 then it sets the 'LONGLBA' flag in the command indicating that the addresses in the associated parameter block are 8 byte quantities. When value is 0 then it clears the 'LONGLBA' flag in the command indi- cating that the addresses in the associated parameter block are 4 byte quantities. If this option is not given then 4 byte quantities are assumed unless one of the address is too large. -g, --grown use the SCSI READ DEFECT DATA (10) command to determine the number of elements in the "grown defect list". When this option is given there is no reassignment of blocks (i.e. this utility is passive). When this option is given then the --address= option is not permitted. See the discussion below concerning the relationship between reassigned blocks and the grown defect list. This list is sometimes referred to as the GLIST. -h, --help output the usage message then exit. -l, --longlist=0 | 1 sets the REASSIGN BLOCKS cdb field of the same name to the given value. Only 1000 addresses are permitted so there should be no need to specify a value of 1. The short list variant restricts the parameter block length to 2 ** 16 bytes (i.e. about 16000 4 byte addresses or 8000 8 byte addresses). Added for completeness. -p, --primary use the SCSI READ DEFECT DATA (10) command to determine the number of elements in the "primary defect list" which is established during the manufacturing process. When this option is given there is no reassignment of blocks (i.e. this utility is passive). When this option is given then the --address= option is not permitted. This list is sometimes referred to as the PLIST. -v, --verbose increase the level of verbosity, (i.e. debug output). -V, --version print the version string and then exit. sg3_utils-1.23 Last change: January 2007 2 SG3_UTILS SG_REASSIGN(8) NOTES Note that if the ARRE field (for reads) and/or the AWRE field (for writes) are set in the "Read Write Error Recovery" mode page then recoverable read and/or write errors cause automatic reassignment of the defective block. The PER bit in the same mode page controls whether a RECOVERED ERROR sense key is reported on not (PER=1 implies do report). Irrespective of the ARRE, AWRE or PER field set- tings, the error counter log pages reflect any errors (recovered or otherwise). Whenever a block is reassigned, a new entry is added in the "grown" defect list. Apart from doing selftests (see sg_senddiag or smartmontools) regu- larly, monitoring the grown defect list of a disk is a rea- sonable metric of its health. If the grown list starts grow- ing quickly that is an ominous sign. The best grown defect lists are empty ones. The number of elements in the grown defect list can be viewed with the --grown option. The con- tents of the grown defect list can be viewed with the 'sginfo -G' utility. If an unrecoverable error is detected at a logical block address then REASSIGN BLOCKS is needed to reassign the block. Also if the ARRE and/or AWRE fields are clear and a recoverable error is detected then the logical block in question may be reassigned with this utility (otherwise the error counter log pages will continually be incremented for each recovered access). The number of blocks held in reserve for the purposes of REASSIGN BLOCKS is vendor specific and may well be limited to the zone within the media where the original (defective) block lay. When this number is exhausted subsequent invoca- tions of this utility may result in a sense key of hardware error and an additional sense of 'No defect spare location available'. The next step would be to reformat the disk (or get a replacement). The SBC-2 draft standard (revision 16) notes that when mul- tiple addresses are given to the SCSI REASSIGN BLOCKS com- mand and there is some failure at one of the later addresses then all addresses prior to that have already be reassigned. Care should be taken in such a case. Re-executing the com- mand with the same addresses will cause the earlier addresses to be reassigned again. At some stage the disk will run out of reserved locations. So unless a large number of addresses are involved it may be safer to reassign them one address at a time. EXIT STATUS The exit status of sg_reassign is 0 when it is successful. Otherwise see the sg3_utils(8) man page. sg3_utils-1.23 Last change: January 2007 3 SG3_UTILS SG_REASSIGN(8) AUTHORS Written by Douglas Gilbert. REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2005-2007 Douglas Gilbert This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_format,sginfo,sg_senddiag(all in sg3_utils), sdparm(sdparm), smartmontools(internet, sourceforge) sg3_utils-1.23 Last change: January 2007 4 SG3_UTILS SG_REQUESTS(8) NAME sg_requests - send one or more SCSI REQUEST SENSE commands SYNOPSIS sg_requests [--desc] [--help] [--hex] [--num=NUM] [--raw] [--status] [--time] [--verbose] [--version] DEVICE DESCRIPTION Send REQUEST SENSE command to DEVICE and output the response which is expected to be in sense data format. Both fixed and descriptor format are supported. OPTIONS Arguments to long options are mandatory for short options as well. -d, --desc sets the DESC bit in the REQUEST SENSE SCSI cdb. The DEVICE should return sense data in descriptor (rather than fixed) format. This will only occur if the DEVICE recognizes descriptor format (SPC-3 and later). If the device is pre SPC-3 then setting a bit in a reserved field may cause a check condition status with an ille- gal request sense key. -h, --help output the usage message then exit. -H, --hex output response in ASCII hexadecimal. -n, --num=NUM perform NUM SCSI REQUEST SENSE commands, stopping when either NUM is reached or an error occurs. The default value for NUM is 1 . -r, --raw output response in binary (to stdout). -s, --status if the last REQUEST SENSE finished without error (from SCSI status or autosense) then the contents of the parameter data are analysed as sense data and the exit status is set accordingly. The default action (when this option is not given) is to ignore the contents of the parameter data for the purposes of setting the exit status. Some types of error set a sense key of "NO SENSE" with non-zero information in the additional sense code (e.g. the FAILURE PREDICTION THRESHOLD EXCEEDED group of codes); this results in an exit status value of 10. If the sense key is "NO SENSE" and both asc and ascq are zero then the exit status is set sg3_utils-1.23 Last change: January 2007 1 SG3_UTILS SG_REQUESTS(8) to 0 . See the sg3_utils(8) man page for exit status values. -t, --time time the SCSI REQUEST SENSE command(s) and calculate the average number of operations per second. -v, --verbose increase the level of verbosity, (i.e. debug output). Additionally the response (if received) is output in ASCII-HEX. Use this option multiple times for greater verbosity. -V, --version print the version string and then exit. NOTES In SCSI 1 and 2 the REQUEST SENSE command was very important for error and warning processing in SCSI. The autosense capability rendered this command almost superfluous. However recent SCSI drafts (e.g. SPC-3 rev 23 and SBC-2 rev 16) increase the utility of the REQUEST SENSE command. Idle and standby power conditions can now be detected with this command; a progress indication is given during FORMAT (when that command was started with with IMMED=1 in its parameter header); and the Filemark, ILI and EOM bits may be set (e.g. by a tape drive). Interestingly the sense key is set to "no sense" while the asc/ascq code convey the information (e.g. 0x5e/0x4 "Standby condition activated by command"). The REQUEST SENSE command is not marked as mandatory in SPC-3 (i.e. for all SCSI devices) but is marked as mandatory in SBC-2 (i.e. for disks), SSC-3 (i.e. for tapes) and MMC-4 (i.e. for CD/DVD drives). EXIT STATUS The exit status of sg_requests is 0 when it is successful. Otherwise see the sg3_utils(8) man page. AUTHORS Written by Douglas Gilbert. REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2004-2007 Douglas Gilbert This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. sg3_utils-1.23 Last change: January 2007 2 SG3_UTILS SG_REQUESTS(8) SEE ALSO sg3_utils sg3_utils-1.23 Last change: January 2007 3 SG3_UTILS SG_RMSN(8) NAME sg_rmsn - sends a SCSI READ MEDIA SERIAL NUMBER command SYNOPSIS sg_rmsn [--help] [--raw] [--verbose] [--version] DEVICE DESCRIPTION Send a SCSI READ MEDIA SERIAL NUMBER command to DEVICE and outputs the response. This command is described in SPC-3 found at www.t10.org . It was originally added to SPC-3 in revision 11 (2003/2/12). It is not an mandatory command and the author has not seen any SCSI devices that support it. OPTIONS Arguments to long options are mandatory for short options as well. -h, --help output the usage message then exit. -r, --raw sends the serial number (if found) to stdout. This out- put may contain non-printable characters (e.g. the serial number is padded with NULLs at the end so its length is a multiple of 4). The default action is to print the serial number out in ASCII-HEX with ASCII characters to the right. All error messages are sent to stderr. -v, --verbose increase the level of verbosity, (i.e. debug output). -V, --version print the version string and then exit. NOTES Device identification information is also found in a stan- dard INQUIRY response and its VPD pages (see sg_vpd). The relevant VPD pages are the "device identification page" (VPD page 0x83) and the "unit serial number" page (VPD page 0x80). The MMC-4 command set for CDs and DVDs has a "media serial number" feature (0x109) [and a "logical unit serial number" feature]. These can be viewed with sg_get_config. EXIT STATUS The exit status of sg_rmsn is 0 when it is successful. Oth- erwise see the sg3_utils(8) man page. sg3_utils-1.23 Last change: January 2007 1 SG3_UTILS SG_RMSN(8) AUTHORS Written by Douglas Gilbert. REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2005-2007 Douglas Gilbert This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_vpd(sg3_utils), sg_get_config(sg3_utils) sg3_utils-1.23 Last change: January 2007 2 SG3_UTILS SG_RTPG(8) NAME sg_rtpg - sends a SCSI REPORT TARGET PORT GROUPS command SYNOPSIS sg_rtpg [--decode] [--help] [--hex] [--raw] [--verbose] [--version] DEVICE DESCRIPTION Send a SCSI REPORT TARGET PORT GROUPS command to DEVICE and outputs the response. Target port group access is described in SPC-3 found at www.t10.org in section 5.8 (in rev 21c dated 2005/1/15). The Report Target Port Groups command is also described in that document. OPTIONS Arguments to long options are mandatory for short options as well. -d, --decode decodes the status code and asymmetric access state from each target port group descriptor returned. The default action is not to decode these values. -h, --help output the usage message then exit. -H, --hex output response in hex (rather than partially or fully decode it). -r, --raw output response in binary to stdout. -v, --verbose increase the level of verbosity, (i.e. debug output). -V, --version print the version string and then exit. NOTES The Report Target Port Groups command should be supported whenever the TPGS bits in a standard INQUIRY response are greater than zero. [View with sg_inq utility.] EXIT STATUS The exit status of sg_rtpg is 0 when it is successful. Oth- erwise see the sg3_utils(8) man page. AUTHORS Written by Douglas Gilbert. sg3_utils-1.23 Last change: January 2007 1 SG3_UTILS SG_RTPG(8) REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2004-2007 Christophe Varoqui and Douglas Gilbert This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_inq(sg3_utils) sg3_utils-1.23 Last change: January 2007 2 SG3_UTILS SG_SAFTE(8) NAME sg_safte - Fetch status from a SCSI Accessed Fault-Tolerant Enclosure (SAF-TE) device SYNOPSIS sg_safte [--config] [--devstatus] [--encstatus] [--flags] [--help] [--hex] [--insertions] [--raw] [--usage] [--ver- bose] [--version] DEVICE DESCRIPTION Fetches enclosure status (via a SCSI READ BUFFER command). The DEVICE should be a SAF-TE device which may be a storage array controller (INQUIRY peripheral device type 0xc) or a generic processor device (INQUIRY peripheral device type 0x3). If no options are given (only the DEVICE argument) then the overall enclosure status as reported by the option --config (Reg.)is reported. OPTIONS Arguments to long options are mandatory for short options as well. The options are arranged in alphabetical order based on the long option name. -c, --config will issues a Read Enclosure Configuration (Reg.)(READ BUFFER ID 0) cdb to the device, which returns a list of the enclosure hardware resources. -d, --devstatus will issue a Read Device Slot Status (Reg.)(READ BUFFER ID 4) cdb to the device, which returns information about the current state of each drive or slot. -s, --encstatus will issue a Read Enclosure Status (Reg.)(READ BUFFER ID 1) cdb to the device, which returns the operational state of the components. -f, --flags will issue a Read Global Flags (Reg.)(READ BUFFER ID 5) cdb to the device, which read the most recent state of the global flags of the RAID processor device. -h, --help output the usage message then exit. -H, --hex output the response to a READ BUFFER command in ASCII hex to stdout. If used once, output the response to the first READ BUFFER command (i.e. with buffer_id=0). This sg3_utils-1.25 Last change: September 2007 1 SG3_UTILS SG_SAFTE(8) should be the enclosure configuration. If used twice (or more often), the response to subsequent READ BUFFER commands is output. -i, --insertions will issue a Read Device Insertions (Reg.)(READ BUFFER ID 3) cdb to the device, which returns information about the number of times devices have been inserted whilst the RAID system was powered on. -r, --raw output the response to a READ BUFFER command in binary to stdout. If used once, output the response to the first READ BUFFER command (i.e. with buffer_id=0). This should be the enclosure configuration. If used twice (or more often), the response to subsequent READ BUFFER commands is output. -u, --usage will issue a Read Usage Statistics (Reg.)(READ BUFFER ID 2) cdb to the device, which returns the information on total usage time and number of power-on cycles of the RAID device. -v, --verbose increase the level of verbosity, (i.e. debug output). -V, --version print the version string and then exit. NOTES The implementation is based on the intermediate review docu- ment eg as found at http://www.intel.com/design/servers/ipmi/saf-te.htm As the specification was never finalized this document serves as the de-facto standard. Similar functionality is provided by SPC-4 SCSI Enclosure Services devices (Peripheral device type 0xd), which can be queried with the sg_ses utility. EXAMPLES To view the configuration: sg_safte /dev/sg1 To view the device slot status: sg_safte --devstatus /dev/sg1 sg3_utils-1.25 Last change: September 2007 2 SG3_UTILS SG_SAFTE(8) EXIT STATUS The exit status of sg_safte is 0 when it is successful. Oth- erwise see the sg3_utils(8) man page. AUTHORS Written by Hannes Reinecke and Douglas Gilbert. REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2004-2007 Hannes Reinecke and Douglas Gilbert This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_inq, sg_ses (in sg3_utils package); safte-monitor sg3_utils-1.25 Last change: September 2007 3 SG3_UTILS SG_SAT_IDENTIFY(8) NAME sg_sat_identify - sends a ATA IDENTIFY (PACKET) DEVICE com- mand via a SCSI to ATA Translation (SAT) layer SYNOPSIS sg_sat_identify [--chk_cond] [--help] [--hex] [--len=12|16] [--packet] [--raw] [--verbose] [--version] DEVICE DESCRIPTION This utility sends either an ATA IDENTIFY DEVICE command or an ATA IDENTIFY PACKET DEVICE command to DEVICE and outputs the response. The devices that respond to these commands are ATA disks and ATAPI devices respectively. Rather than send these commands directly to the device they are sent via a SCSI transport which is assumed to contain a SCSI to ATA Translation (SAT) Layer (SATL). The SAT standard (SAT ANSI INCITS 431-2007, prior draft: sat-r09.pdf at www.t10.org) defines two SCSI "ATA PASS-THROUGH" commands: one using a 16 byte "cdb" and the other with a 12 byte cdb. This utility defaults to using the 16 byte cdb variant. The SATL may be in an operating system driver, in host bus adapter firmware or in some external enclosure. OPTIONS Arguments to long options are mandatory for short options as well. -c, --chk_cond sets the CK_COND bit in the ATA PASS-THROUGH SCSI cdb. The default setting is clear (i.e. 0). When set the SATL should yield a sense buffer containing a ATA Result descriptor irrespective of whether the command succeeded or failed. When clear the SATL should only yield a sense buffer containing a ATA Result descriptor if the command failed. -h, --help outputs the usage message summarizing command line options then exits. Ignores DEVICE if given. -H, --hex outputs the ATA IDENTIFY (PACKET) DEVICE response in hex. The default action (i.e. without any '-H' options) is to output the response in hex, grouped in 16 bit words (i.e. the ATA standard's preference). When given once, the response is output in ASCII hex bytes (i.e. the SCSI standard's preference). When given twice (i.e. '-HH') the output is in hex, grouped in 16 bit words, the same as the default but without a header. When given thrice (i.e. '-HHH') the output is in hex, grouped in 16 bit words, in a format that is acceptable sg3_utils-1.24 Last change: May 2007 1 SG3_UTILS SG_SAT_IDENTIFY(8) for 'hdparm --Istdin' to process. -l, --len=12 | 16 this is the length of the SCSI cdb used for the ATA PASS-THROUGH commands. The argument can either be 12 or 16. The default is 16. The larger cdb size is needed for 48 bit LBA addressing of ATA devices. On the other hand some SCSI transports cannot convey SCSI commands longer than 12 bytes. -p, --packet send an ATA IDENTIFY PACKET DEVICE command (via the SATL). The default action is to send an ATA IDENTIFY DEVICE command. -r, --raw output the ATA IDENTIFY (PACKET) DEVICE response in binary. The output should be piped to a file or another utility when this option is used. The binary is sent to stdout, and errors are sent to stderr. -v, --verbose increases the level or verbosity. -V, --version print out version string NOTES Since the response to the IDENTIFY (PACKET) DEVICE command is very important for the correct use of an ATA(PI) device (and is typically the first command sent), a SATL should provide an ATA Information VPD page which contains the simi- lar information. The SCSI ATA PASS-THROUGH (12) command's opcode is 0xa1 and it clashes with the MMC set's BLANK command used by cd/dvd writers. So a SATL in front of an ATAPI device that uses MMC (i.e. has peripheral device type 5) probably should treat opcode 0xa1 as a BLANK command and send it through to the cd/dvd drive. The ATA PASS-THROUGH (16) command's opcode (0x85) does not clash with anything so it is a better choice. In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic (sg) device. In the 2.6 series block devices (e.g. disks and ATAPI DVDs) can also be specified. For example "sg_inq /dev/sda" will work in the 2.6 series kernels. From lk 2.6.6 other SCSI "char" device names may be used as well (e.g. "/dev/st0m"). EXIT STATUS The exit status of sg_sat_identify is 0 when it is sg3_utils-1.24 Last change: May 2007 2 SG3_UTILS SG_SAT_IDENTIFY(8) successful. Otherwise see the sg3_utils(8) man page. AUTHOR Written by Doug Gilbert REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2006-2007 Douglas Gilbert This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_vpd(sg3_utils), sg_inq(sg3_utils), sdparm(sdparm), hdparm(hdparm) sg3_utils-1.24 Last change: May 2007 3 SG3_UTILS SG_SAT_SET_FEATURES(8) NAME sg_sat_set_featutes - sends a ATA SET FEATURES command via a SCSI to ATA Translation (SAT) layer SYNOPSIS sg_sat_set_features [--count=CO] [--chk_cond] [--feature=FEA] [--help] [--len=16|12] [--lba=LBA] [--ver- bose] [--version] DEVICE DESCRIPTION This utility sends an ATA SET FEATURES command to the DEV- ICE. This command is used to change settings of ATA non-packet (i.e. disks) and packet devices (e.g. cd/dvd drives). Rather than send the SET FEATURES command directly to the device it is sent via a SCSI transport which is assumed to contain a SCSI to ATA Translation (SAT) Layer (SATL). The SAT standard (SAT ANSI INCITS 431-2007; prior draft: sat-r09.pdf at www.t10.org) defines two SCSI "ATA PASS-THROUGH" commands: one using a 16 byte "cdb" and the other with a 12 byte cdb. This utility defaults to the 16 byte cdb variant. The SATL may be in an operating system driver, in host bus adapter firmware or in some external enclosure. The features can be read using the sg_sat_identify utility which uses either the ATA IDENTIFY DEVICE (for non-packet devices) or the IDENTIFY PACKET DEVICE (for packet devices) command. OPTIONS Arguments to long options are mandatory for short options as well. -c, --count=CO the number CO is placed in the "count" field in the ATA SET FEATURES command. Only some subcommands (a term used for the value placed in the "feature" field) require the count field to be set. The default value placed in the "count" field is 0. -C, --chk_cond sets the CK_COND bit in the ATA PASS-THROUGH SCSI cdb. The default setting is clear (i.e. 0). When set the SATL should yield a sense buffer containing a ATA Result descriptor irrespective of whether the ATA com- mand succeeded or failed. When clear the SATL should only yield a sense buffer containing a ATA Result descriptor if the ATA command failed. -f, --feature=FEA the value FEA is placed in the "feature" field in the sg3_utils-1.25 Last change: August 2007 1 SG3_UTILS SG_SAT_SET_FEATURES(8) ATA SET FEATURES command. The term "subcommand" is sometimes used for this value. The default value placed in the "feature" field is 0 which is reserved and hence should not change anything. Two common examples are 2h to enable the write cache and 82h to disable it. -h, --help outputs the usage message summarizing command line options then exits. Ignores DEVICE if given. -l, --len=16 | 12 this is the length of the SCSI cdb used for the ATA PASS-THROUGH commands. The argument can either be 16 or 12. The default is 16. Some SCSI transports cannot convey SCSI commands longer than 12 bytes. -L, --lba=LBA the number LBA is placed in the "lba" field in the ATA SET FEATURES command. Only some subcommands (a term used for the value placed in the "feature" field) require the lba field to be set. This value is not a "logical block address" as the acronym might imply. The default value placed in the "lba" field is 0. -v, --verbose increases the level or verbosity. -V, --version print out version string NOTES In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic (sg) device. In the 2.6 series block devices (e.g. disks and ATAPI DVDs) can also be specified. For example "sg_inq /dev/sda" will work in the 2.6 series kernels. From lk 2.6.6 other SCSI "char" device names may be used as well (e.g. "/dev/st0m"). EXIT STATUS The exit status of sg_sat_set_features is 0 when it is suc- cessful. Otherwise see the sg3_utils(8) man page. AUTHOR Written by Doug Gilbert REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2007 Douglas Gilbert This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR sg3_utils-1.25 Last change: August 2007 2 SG3_UTILS SG_SAT_SET_FEATURES(8) A PARTICULAR PURPOSE. SEE ALSO sg_sat_identify(sg3_utils), sg_inq(sg3_utils), sdparm(sdparm), hdparm(hdparm) sg3_utils-1.25 Last change: August 2007 3 SG3_UTILS SG_SENDDIAG(8) NAME sg_senddiag - performs a SCSI SEND DIAGNOSTIC command SYNOPSIS sg_senddiag [--doff] [--extdur] [--help] [--hex] [--list] [--pf] [--raw=H,H...] [--raw=-] [--selftest=ST] [--test] [--uoff] [--verbose] [--version] DEVICE sg_senddiag [-doff] [-e] [-h] [-H] [-l] [-pf] [-raw=H,H...] [-raw=-] [-s=ST] [-t] [-uoff] [-v] [-V] [-?] DEVICE DESCRIPTION This utility sends a SCSI SEND DIAGNOSTIC command to the DEVICE. It can issue self-tests, find supported diagnostic pages or send arbitrary diagnostic pages. When the --list option and a DEVICE are given then the util- ity sends a SCSI RECEIVE DIAGNOSTIC RESULTS command to fetch the response (i.e. the page numbers of supported diagnostic pages). When the --list option is given without a DEVICE then a list of diagnostic page names and their numbers, known by this utility, are listed. This utility supports two command line syntaxes, the pre- ferred one is shown first in the synopsis and explained in this section. A later section on the old command line syntax outlines the second group of options. OPTIONS Arguments to long options are mandatory for short options as well. -d, --doff set the Device Offline (DevOffL) bit (default is clear). Only significant when --test option is set for the default self-test. When set other operations on any logical units controlled by the this device server (target) may be affected (delayed) while a default self-test is underway. -e, --extdur outputs the expected extended self-test duration. The duration is given in seconds (and minutes in parentheses). This figure is obtained from mode page 0xa (i.e. the control mode page). -h, --help print usage message then exit. -H, --hex sg3_utils-1.25 Last change: October 2007 1 SG3_UTILS SG_SENDDIAG(8) outputs response from RECEIVE DIAGNOSTIC RESULTS in hex rather than decode it. -l, --list when a DEVICE is also given lists the names of all diagnostic pages supported by this device. The request is sent via a SEND DIAGNOSTIC command (with the "pF" bit set) and the response is fetched by a RECEIVE DIAG- NOSTIC RESULTS command. When used in the absence of a --list argument then a list of diagnostic page names and their numbers, known by this utility, are listed. -O, --old switch to older style options. -p, --pf set Page Format (PF) bit. By default it is clear (i.e. 0) unless the list --list option is given in which case the Page Format bit is set (as required by SPC-3). -r, --raw=H,H... string of comma separated hex numbers each of which should resolve to a byte value (i.e. 0 to ff inclusive). This sequence forms a diagnostic page to be sent with the SCSI SEND DIAGNOSTIC command. Mostly likely the --pf option should also be given. -r, --raw=- reads sequence of bytes from stdin. The sequence may be comma, space, tab or linefeed (newline) separated. If a line contains "#" then the remaining characters on that line are ignored. Otherwise each non separator charac- ter should resolve to a byte value (i.e. 0 to ff inclusive). This sequence forms a diagnostic page to be sent with the SCSI SEND DIAGNOSTIC command. Mostly likely the --pf option should also be given. -s, --selftest=ST where ST is the self-test code. The default value is 0 which is inactive. Some other values: 1 : background short self-test 2 : background extended self-test 4 : aborts a (background) self-test that is in pro- gress 5 : foreground short self-test 6 : foreground extended self-test This option is mutually exclusive with default self-test (i.e. can't have (ST > 0) and --test). -t, --test sets the _default_ Self Test (SelfTest) bit. By default this is clear (0). The --selftest=ST option should not sg3_utils-1.25 Last change: October 2007 2 SG3_UTILS SG_SENDDIAG(8) be active together with this option. Both the --doff and/or --uoff options can be used with this option. -u, --uoff set the Unit Offline (UnitOffL) bit (default is clear). Only significant when --test option is set for the default self-test. When set other operations on this logical unit may be affected (delayed) while a default self-test is underway. Some devices (e.g. Fujitsu disks) do more tests when this bit is set. -v, --verbose increase level of verbosity. Can be used multiple times. -V, --version print out version string then exit. NOTES All devices should support the default self-test. The 'short' self-test codes should complete in 2 minutes or less. The 'extended' self-test codes' maximum duration is vendor specific (e.g. a little over 10 minutes with the author's disks). The foreground self-test codes wait until they are completed while the background self-test codes return immediately. The results of both foreground and back- ground self-test codes are placed in the 'self-test results' log page (see sg_logs(8)). The SCSI command timeout for this utility is set to 60 minutes to allow for slow foreground extended self-tests. If the DEVICE is a disk then no file systems residing on that disk should be mounted during a foreground self-test. The reason is that other SCSI commands may become queued behind the foreground self-test and timeout. When the --raw=H,H... option is given then self-tests should not be selected. However the --pf (i.e. "page format") option should be given. The length of the diagnostic page to be sent is derived from the number of bytes given to the --raw=H,H... option. The diagnostic page code (number) should be the first byte of the sequence (i.e. as dictated by SPC-3 diagnostic page format). The SAS 1.1 protocol specific diagnostic page could be sent with this option, for example. The examples subdirectory in the sg3_utils packages contains two example scripts that turn on the CJTPAT (jitter pattern) on some SAS disks (one script for each phy). One possible invocation is: 'sg_senddiag --pf --raw=- /dev/sg2 < .../sdiag_sas_p1_cjtpat.txt' Arbitrary diagnostic pages can be read (in hex) with the sg_ses(8) utility (not only those defined in SES-2). sg3_utils-1.25 Last change: October 2007 3 SG3_UTILS SG_SENDDIAG(8) If the utility is used with no options (e.g. "sg_senddiag /dev/sg1") Then a degenerate SCSI SEND DIAGNOSTIC command is sent with zero in all its fields apart from the opcode. Some devices report this as an error while others ignore it. It is not entirely clear from SPC-3 if it is invalid to send such a command. In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic (sg) device. In the 2.6 series block devices (e.g. SCSI disks and DVD drives) can also be specified. For exam- ple 'sg_senddiag -t /dev/sda' will work in the 2.6 series kernels. To access SCSI enclosures see the sg_ses(8) utility. sg_ses uses the SCSI SEND DIAGNOSTIC and RECEIVE DIAGNOSTIC RESULTS commands as outlined in the SES-2 (draft) standard. EXIT STATUS The exit status of sg_senddiag is 0 when it is successful. Otherwise see the sg3_utils(8) man page. OLDER COMMAND LINE OPTIONS The options in this section were the only ones available prior to sg3_utils version 1.23 . In sg3_utils version 1.23 and later these older options can be selected by either set- ting the SG3_UTILS_OLD_OPTS environment variable or using '--old' (or '-O) as the first option. -doff set the Device Offline (DevOffL) bit (default is clear). Only significant when -t option is set for the default self-test. Equivalent to --doff in the main description. -e outputs the expected extended self-test duration. Equivalent to --extdur in the main description. -h outputs response from RECEIVE DIAGNOSTIC RESULTS in hex rather than decode it. -H outputs response from RECEIVE DIAGNOSTIC RESULTS in hex rather than decode it. -l when a DEVICE is also given lists the names of all diagnostic pages supported by this device. The request is sent via a SEND DIAGNOSTIC command (with the "pf" bit set) and the response is fetched by a RECEIVE DIAG- NOSTIC RESULTS command. When used in the absence of a DEVICE argument then a list of diagnostic page names and their numbers, known by this utility, are listed. -N switch to the newer style options. sg3_utils-1.25 Last change: October 2007 4 SG3_UTILS SG_SENDDIAG(8) -pf set Page Format (PF) bit. By default it is clear (i.e. 0) unless the -l option is given in which case the Page Format bit is set (as required by SPC-3). -raw=H,H... string of comma separated hex numbers each of which should resolve to a byte value (i.e. 0 to ff inclusive). This sequence forms a diagnostic page to be sent with the SCSI SEND DIAGNOSTIC command. Mostly likely the -pf option should also be given. -raw=- reads sequence of bytes from stdin. The sequence may be comma, space, tab or linefeed (newline) separated. If a line contains "#" then the remaining characters on that line are ignored. Otherwise each non separator charac- ter should resolve to a byte value (i.e. 0 to ff inclusive). This sequence forms a diagnostic page to be sent with the SCSI SEND DIAGNOSTIC command. Mostly likely the -pf option should also be given. -s=ST where ST is the self-test code. The default value is 0 which is inactive. A value of 1 selects a background short self-test; 2 selects a background extended self-test; 5 selects a foreground short self-test; 6 selects a foreground extended test. A value of 4 will abort a (background) self-test that is in progress. This option is mutually exclusive with default self-test (i.e. -t). -t sets the _default_ Self Test (SelfTest) bit. By default this is clear (0). The -s=ST option should not be active together with this option. Both the -doff and/or -uoff options can be used with this option. -uoff set the Unit Offline (UnitOffL) bit (default is clear). Equivalent to --uoff in the main description. -v increase level of verbosity. Can be used multiple times. -V print out version string then exit. -? output usage message. Ignore all other parameters. AUTHOR Written by Doug Gilbert REPORTING BUGS Report bugs to . sg3_utils-1.25 Last change: October 2007 5 SG3_UTILS SG_SENDDIAG(8) COPYRIGHT Copyright O 2003-2007 Douglas Gilbert This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_ses(8), sg_logs(8), smartmontools(see net) sg3_utils-1.25 Last change: October 2007 6 SG3_UTILS SG_SES(8) NAME sg_ses - send controls and fetch status from a SCSI Enclo- sure Services (SES) device SYNOPSIS sg_ses [--byte1=B1] [--control] [--data=H,H...] [--filter] [--help] [--hex] [--inner-hex] [--list] [--page=PG] [--raw] [--status] [--verbose] [--version] DEVICE DESCRIPTION Send controls to a SES device (via a SCSI SEND DIAGNOSTIC command) or fetches status (via a SCSI RECEIVE DIAGNOSTIC RESULTS command). The DEVICE should be a SES device which may be a dedicated enclosure services processor (INQUIRY peripheral device type 0xd) or attached to another type of SCSI device (e.g. a disk) in which case the EncServ bit set in its INQUIRY response. If no options are given (only the DEVICE argument) then all diagnostic pages supported by the device (including SES pages) are listed. OPTIONS Arguments to long options are mandatory for short options as well. The options are arranged in alphabetical order based on the long option name. -b, --byte=B1 some control pages need byte 1 (i.e. the second byte) of the cdb set. Only required in rare cases when the --control option is also set. Default is 0; B1 is in decimal unless it is prefixed by '0x' or '0X' (or has a trailing 'h' or 'H'). -c, --control will send control information to the DEVICE via a SCSI SEND DIAGNOSTIC command. Cannot give both this option and --status. The Enclosure control, String Out, Threshold Out, Array control (obsolete in SES-2) and Subenclosure String Out diagnostic pages can be set currently. -d, --data=H,H... permits a string of comma separated (ASCII) hex digits to be specified (limit 512). This allows the parameters to a control diagnostic page to be specified. The string given should not include the first 4 bytes (i.e. page code and length). See next entry for using stdin. -d, --data=- reads a data string from stdin. Spaces, tabs and line feeds additionally are permitted as separators. sg3_utils-1.25 Last change: October 2007 1 SG3_UTILS SG_SES(8) -f, --filter cuts down on the amount of output from the enclosure status diagnostic page. When this option is given, any line which has all its binary flags cleared (i.e. 0) is filtered out (i.e. ignored). If a line has some other value on it (e.g. a temperature) then it is output. -h, --help output the usage message then exit. -H, --hex output the response in hexadecimal. -i, --inner-hex the outer levels of a status diagnostic page are decoded and printed out but the innermost level (e.g. the element status descriptor) is output in hex. Imple- mented for the more complex diagnostic pages. -l, --list list all known diagnostic page names and SES elements. DEVICE is ignored and utility exits. -p, --page=PG where PG is a page code. Assumed to be in decimal unless prefixed by 0x for hex. Valid range is 0 to 255 (0x0 to 0xff) inclusive. Default is page_code 0 (i.e. "Supported diagnostic pages"). -r, --raw outputs the chosen status page in (ASCII) hex in a for- mat suitable for a later invocation using the --data= option. A status diagnostic page less its first 4 bytes (page code and length) is output. When used twice (e.g. -rr) outputs full diagnostic page in binary to stdout. -s, --status will fetch status diagnostic page from the DEVICE via a SCSI RECEIVE DIAGNOSTIC RESULTS command. If this option is not given and --control is not given then --status is assumed. -v, --verbose increase the level of verbosity, (i.e. debug output). -V, --version print the version string and then exit. NOTES Currently all status pages, control pages and element types defined in SES-2 revision 17 (14th May 2007) are decoded. sg3_utils-1.25 Last change: October 2007 2 SG3_UTILS SG_SES(8) This utility can be used to fetch arbitrary (i.e. non SES) diagnostic pages (using the SCSI READ DIAGNOSTIC command). To this end the --page=PG and --hex options would be appropriate. Arbitrary diagnostic pages can be sent to a device with the sg_senddiag utility. There is a related command set called SAF-TE (SCSI attached fault-tolerant enclosure) for enclosure (including RAID) status and control. SCSI devices that support SAF-TE report "Processor" peripheral device type (0x3) in their INQUIRY response. See the sg_safte utility in this package or safte-monitor on the internet. EXAMPLES To view the supported pages: sg_ses /dev/sda To view the configuration page: sg_ses --page=1 /dev/sda To view the status page: sg_ses --page=2 /dev/sda Changing a temperature threshold is possible, if a little awkward. The current thresholds can be shown with: sg_ses --page=5 /dev/sda The threshold to be changed can be chosen. Then output the threshold page in hex (suitable for editing) with: sg_ses --page=5 --raw /dev/sda > t Then with the aid of the SES-2 document (in revision 9: sec- tion 6.1.8) use your favourite editor to change t. The change can be sent to the device with: sg_ses --control --page=5 --data=- /dev/sda < t If the above is successful, the threshold should have been changed. To check try: sg_ses --page=5 /dev/sda again. EXIT STATUS The exit status of sg_ses is 0 when it is successful. Other- wise see the sg3_utils(8) man page. sg3_utils-1.25 Last change: October 2007 3 SG3_UTILS SG_SES(8) AUTHORS Written by Douglas Gilbert. REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2004-2007 Douglas Gilbert This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_inq, sg_safte, sg_senddiag (in sg3_utils package); safte-monitor (internet) sg3_utils-1.25 Last change: October 2007 4 SG3_UTILS SG_START(8) NAME sg_start - send SCSI START STOP UNIT command to start, stop, load or eject medium SYNOPSIS sg_start [0] [1] [--eject] [--help] [--fl=FL] [--immed] [--load] [--loej] [--pc=PC] [--start] [--stop] [--verbose] [--version] DEVICE sg_start [--eject] [--fl=FL] [-i] [--imm=0|1] [--load] [--loej] [--pc=PC] [--start] [--stop] [-v] [-V] [0|1] DEVICE DESCRIPTION sg_start sends a SCSI START STOP UNIT command to the DEVICE with the selected options. The most used options are --stop to spin down a disk and --start to spin up a disk. Using --start on a disk that is already spinning is harmless. There is also finer grain control with "power conditions": active, idle and standby. This is set with the --pc=PC option. In some contexts the "stop" state can be considered an additional power condition. Devices that contain removable media such as cd/dvds can use the --loej option to load the medium when used in conjunc- tion with --start (i.e. load medium then spin up). Alterna- tively --loej may be used to eject the medium when used in conjunction with --stop (i.e. spin down then eject medium). More simply, the loading or ejecting of a removable medium can be requested with the --load or --eject' option. If no option or argument is given then a --start is assumed; as the utility's name suggests. This utility supports two command line syntaxes, the pre- ferred one is shown first in the synopsis and explained in this section. A later section on the old command line syntax outlines the second group of options. OPTIONS Arguments to long options are mandatory for short options as well. 0 same action as --stop. 1 same action as --start. -e, --eject stop the medium and eject it from the drive. Only appropriate for a device with removable medium. Might be ignored (prevented), see below. -h, --help sg3_utils-1.25 Last change: October 2007 1 SG3_UTILS SG_START(8) print out the usage message then exit. -f, --fl=FL sets the format layer number for the disc to "jump" to (defined in MMC-5). Values of FL can be 0 to 3. When this option is chosen, the FL, LoEj and Start bits are set in the cdb as required by MMC-5; thus the user does not need to set the --start and/or --load options. -i, --immed sets the IMM bit on the START STOP UNIT command so this utility will return immediately and not wait for the media to complete the requested action. The default is to wait until the media to complete the requested action before returning. -l, --load load the medium in the drive and start it. Only appropriate for a removable medium. -L, --loej sets the LOEJ bit on the START STOP UNIT command. This loads the media when the unit is started or eject it when the unit is stopped (i.e. works in conjunction with START bit in cdb). This option is ignored if 'pc > 0'. Default is off (i.e. don't attempt to load or eject media). If a start/start indication is not given (i.e. neither --start nor --stop) and this option is given then a load and start action is assumed. -O, --old switch to older style options. -p, --pc=PC where PC is the 'power conditions' value. 0 to 15 (inclusive) are valid. Default value is 0. When '--pc=0' then --eject, --load, --loej, --start and --stop are active. Some common values are 1 for the "active" power condition (SBC); 2 for the idle power condition; 3 for the standby power condition; 5 for sleep power condition (MMC); 7 for LU_CONTROL (SBC), 0xa (decimal 10) for FORCE_IDLE_0 (SBC) and 0xb (decimal 11) for FORCE_STANDBY_0 (SBC). See recent SBC-3, MMC-5 and SAS drafts at www.t10.org for more information. -s, --start start (spin-up) the device. This sets the START bit in the cdb. Using this option on an already started device is harmless. In the absence of other options, this option defaults (i.e. set the START cdb bit). sg3_utils-1.25 Last change: October 2007 2 SG3_UTILS SG_START(8) -S, --stop stop (spin-down) the device. This clears the START bit in the cdb. -v, --verbose increase the level of verbosity. Can be used multiple times. -V, --version print out version string then exit. NOTES To avoid confusion, only one of 0, 1 --eject, --load, --start and --stop should be given. There is an associated "power condition" mode page (0x1a) in which timer values can be set for transitioning to either idle or standby state after a period of inactivity. The sdparm utility can be used to view the power condition mode page and if required change it. If a device is in either idle or standby power condition state then a REQUEST SENSE command (see the sg_requests utility) should yield a sense key of "no sense" and an additional sense code of "Low power condition on" on recent SCSI devices. Ejection of removable media (e.g. 'sg_start --eject /dev/hdd' where the device is an ATAPI cd/dvd drive) may be prevented by a prior SCSI PREVENT ALLOW MEDIUM REMOVAL com- mand (see sg_prevent). In this case this utility should fail with an error generated by the device: illegal request / medium removal prevented. This can be overridden using sg_prevent or, for example, 'sdparm --command=unlock /dev/hdd'. The SCSI TEST UNIT READY command can be used to find out whether a device is ready to transfer data. If rotating media is stopped or still coming up to speed, then the TEST UNIT READY command will yield a "not ready" sense key and an more informative additional sense code. See the sg_turs utility. In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic (sg) device. In the 2.6 series block devices (e.g. SCSI disks and DVD drives) can also be specified. For exam- ple "sg_start 0 /dev/sda" will work in the 2.6 series ker- nels. EXIT STATUS The exit status of sg_start is 0 when it is successful. Oth- erwise see the sg3_utils(8) man page. sg3_utils-1.25 Last change: October 2007 3 SG3_UTILS SG_START(8) OLDER COMMAND LINE OPTIONS The options in this section were the only ones available prior to sg3_utils version 1.23 . In sg3_utils version 1.23 and later these older options can be selected by either set- ting the SG3_UTILS_OLD_OPTS environment variable or using '--old' (or '-O) as the first option. Note that the action of --loej is slightly different in the older interface: when neither --start nor --stop (nor prox- ies for them) are given, --loej performs an eject operation. In the same situation the newer interface will perform a load operation. Earlier versions of sg_start had a '-s' option to perform a SYNCHRONIZE CACHE command before the START STOP UNIT command was issued. According to recent SBC-2 drafts this is done implicitly if required. Hence the '-s' option has been dropped. All options, other than '-v' and '-V', can be given with a single "-". For example: "sg_start -stop /dev/sda" and "sg_start --stop /dev/sda" are equivalent. The single "-" form is for backward compatibility. 0 stop (spin-down) DEVICE. 1 start (spin-up) DEVICE. --eject stop the medium and eject it from the drive. --fl=FL sets the format layer number for the disc to "jump" to (defined in MMC-5). -i sets the IMM bit on the START STOP UNIT command so this utility will return immediately and not wait for the media to spin down. Same effect as '--imm=1'. The default action (without this option or a '--imm=1' option) is to wait until the media spins down before returning. --imm=0|1 when the immediate bit is 1 then this utility returns immediately after the device has received the command. When this option is 0 (the default) then the utility returns once the command has completed its action (i.e. it waits until the device is started or stopped). --load load the medium in the drive and start it. sg3_utils-1.25 Last change: October 2007 4 SG3_UTILS SG_START(8) --loej sets the LOEJ bit in the START STOP UNIT cdb. When a "start" operation is indicated, then a load and start is performed. When a "stop" operation is indicated, then a stop and eject is performed. When neither a "start" or "stop" operation is indicated does a stop and eject. [Note that the last action differs from the new interface in which the option of this name defaults to load and start.] -N switch to the newer style options. --pc=PC where PC is the 'power conditions' value (in hex). 0 to f (inclusive) are valid. Default value is 0. --start start (spin-up) DEVICE. --stop stop (spin-down) DEVICE. Same meaning as "0" argument. -v verbose: outputs SCSI command in hex to console before with executing it. '-vv' and '-vvv' are also accepted yielding greater verbosity. -V print out version string then exit. AUTHOR Written by K. Garloff and D. Gilbert REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2002-2007 Kurt Garloff, Douglas Gilbert This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_prevent(sg3_utils), sg_requests(sg3_utils), sg_turs(sg3_utils) sdparm(sdparm) sg3_utils-1.25 Last change: October 2007 5 SG3_UTILS SG_STPG(8) NAME sg_stpg - sends a SCSI SET TARGET PORT GROUPS command SYNOPSIS sg_stpg [--active] [--help] [--hex] [--offline] [--optim- ized] [--raw] [--standby] [--state=S,S...] [--tp=P,P...] [--unavailable] [--verbose] [--version] DEVICE DESCRIPTION Send a SCSI SET TARGET PORT GROUPS command to DEVICE. This utility has different modes depending on whether the --tp= option is given. If --tp= is given then the SET TARGET PORT GROUPS command parameter block is built with a descriptor for each element in the list given to --tp=. The corresponding asymmetric access state value is either taken from the --state= list or, if that is not given, from one of the explicit state options (e.g. --unavailable), used repeatedly if required. If --tp= is not given then a sequence of SCSI commands are sent to the DEVICE leading up to the SET TARGET PORT GROUPS command. First an INQUIRY is sent to fetch the device iden- tification VPD page to find the (primary) target port group associated with DEVICE. Then a REPORT TARGET PORT GROUPS command is issued to find the current state and whether a transition to the requested state is supported. If so the SET TARGET PORT GROUPS command is sent. Target port group access is described in SPC-4 found at www.t10.org in section 5.8 (in rev 11 dated 2007/5/14). The SET TARGET PORT GROUPS command is also described in that document. OPTIONS Arguments to long options are mandatory for short options as well. The options are arranged in alphabetical order based on the long option name. -a, --active set active/non-optimized state. -h, --help output the usage message then exit. -H, --hex output response to the REPORT TARGET PORT GROUPS com- mand in hex then exit. -O, -l, --offline set offline state. This is the appropriate state to set a target port to prior to removing the device. Note sg3_utils-1.25 Last change: September 2007 1 SG3_UTILS SG_STPG(8) that a relative target port identifier should be given with this state (rather than a target port group iden- tifier that all other states take). -o, --optimized set active/optimized state. If no other state options or --tp= option are given then active/optimized is the default state. -r, --raw output response to the REPORT TARGET PORT GROUPS com- mand in binary to stdout then exit. -s, --standby set standby state. Port group shall accept those com- mands listed for "unavailable" state plus LOG SELECT/SENSE, MODE SELECT/SENSE, RECEIVE DIAGNOSTIC RESULTS, SEND DIAGNOSTIC, PERSISTENT RESERVE IN/OUT commands. -S, --state=S,S... specifies a comma separated list (one element of more) of states. Either a number or an abbreviation can be given. A number is assumed to be a decimal number unless it is prefixed by "0x" or has a trailing "h" in which case a hexadecimal value is assumed. Only the values 0, 1, 2, 3 or 14 are accepted. The accepted abbreviations are "an", "ao", "o", "s" or "u"; which represent active/non-optimized(1), active/optimized(0), offline(14), standby(2) or unavalable(3) respectively. -t, --tp=P,P... specifies a comma separated list (one element of more). Each elements is either a target port group identifier (when the corresponding state is other than "offline") or a relative target port identifier (when the corresponding state is "offline"). Each element is assumed to be a decimal number unless it is prefixed by "0x" or has a trailing "h" in which case a hexadecimal value is assumed. -u, --unavailable set unavailable state. Port group shall only accept INQUIRY, REPORT LUNS, REPORT/SET TARGET PORT GROUPS, REQUEST SENSE and READ/WRITE BUFFER commands. -v, --verbose increase the level of verbosity, (i.e. debug output). -V, --version print the version string and then exit. sg3_utils-1.25 Last change: September 2007 2 SG3_UTILS SG_STPG(8) NOTES The SET TARGET PORT GROUPS command should be supported when- ever the TPGS value in a standard INQUIRY response is 2 or 3. [View with sg_inq utility.] Notice that the offline state is termed as a "secondary tar- get port asymmetric access state" and takes a relative tar- get port identifier (i.e. acts on a single target port). All the other states are termed as "primary target port asymmetric access states" and each takes a target port group identifier (i.e. acts on one or more target ports). When --tp= is given then the same number of elements should be given to the --state= option. If more than one list ele- ment is given to --tp= and an equal number of elements is _not_ given to the the --state= option, then if only one state is specified then it is repeated. EXIT STATUS The exit status of sg_stpg is 0 when it is successful. Oth- erwise see the sg3_utils(8) man page. AUTHORS Written by Douglas Gilbert. REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2007 Hannes Reinecke, Christophe Varoqui and Douglas Gilbert This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_inq, sg_rtpg (sg3_utils) sg3_utils-1.25 Last change: September 2007 3 SG3_UTILS SG_SYNC(8) NAME sg_sync - send the scsi command synchronize cache SYNOPSIS sg_sync [--count=COUNT] [--group=GROUP] [--help] [--immed] [--lba=LBA] [--sync-nv] [--verbose] [--version] DEVICE DESCRIPTION Send SYNCHRONIZE CACHE (10) command to DEVICE. This command is defined for SCSI block devices (see SBC-2). If successful this command makes sure that any blocks whose latest ver- sions are held in (volatile) cache are written to (also termed as "synchronized with") the medium. If the --sync-nv option is given and the device has a non-volatile cache then any blocks whose latest versions are held in volatile cache are written to non-volatile cache. If the LBA and COUNT arguments are both zero (their defaults) then all blocks in the cache are synchronized. If LBA is greater than zero while COUNT is zero then blocks in the cache whose addresses are from and including LBA to the highest lba on the device are synchronized. If both LBA and COUNT are non zero then blocks in the cache whose addresses lie in the range LBA to LBA+COUNT-1 inclusive are synchron- ized with the medium. OPTIONS Arguments to long options are mandatory for short options as well. -c, --count=COUNT where COUNT is the number of blocks to synchronize from and including LBA. Default value is 0. When 0 then all blocks in the (volatile) cache from and including LBA argument to the highest block address are synchronized. -g, --group=GROUP where GROUP is the group number which can be between 0 and 31 inclusive. The default value is 0 . Group numbers are used to segregate data collected within the device. This is a new feature in SBC-2 and can probably be ignored for the time being. -h, --help output the usage message then exit. -i, --immed sets the IMMED bit in the SYNCHRONIZE CACHE command. This instructs the device, if the format of the command is acceptable, to return a GOOD status immediately rather than wait for the blocks in the (volatile) cache to be synchronized with (i.e. written to) the medium sg3_utils-1.22 Last change: December 2006 1 SG3_UTILS SG_SYNC(8) (or the non-volatile cache). -l, --lba=LBA where LBA is the lowest logical block address in the (volatile) cache to synchronize to the medium (or the non-volatile cache). Default value is 0 . -s, --sync-nv synchronize the (volatile) cache with the non-volatile cache. Without this option (or if there is no non-volatile cache in the device) the synchronization is with the medium. -v, --verbose increase the level of verbosity, (i.e. debug output). -V, --version print the version string and then exit. NOTES The COUNT, GROUP and LBA arguments may be followed by one of these multiplicative suffixes: c C *1; w W *2; b B *512; k K KiB *1,024; KB *1,000; m M MiB *1,048,576; MB *1,000,000 . This pattern continues for "G", "T" and "P". Also a suffix of the form "x" multiplies the leading number by . The "T" and "P" suffixes can only be used for COUNT and LBA. Alternatively numerical values can be given in hexadecimal preceded by either "0x" or "0X" (or with a trailing "h" or "H"). When hex numbers are given, multipliers cannot be used. EXIT STATUS The exit status of sg_sync is 0 when it is successful. Oth- erwise see the sg3_utils(8) man page. AUTHORS Written by Douglas Gilbert. REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2004-2006 Douglas Gilbert This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_start(sg3_utils) sg3_utils-1.22 Last change: December 2006 2 SG3_UTILS SG_TURS(8) NAME sg_turs - send one or more SCSI TEST UNIT READY commands SYNOPSIS sg_turs [--help] [--number=NUM] [--progress] [--time] [--verbose] [--version] DEVICE sg_turs [-n=NUM] [-p] [-t] [-v] [-V] DEVICE DESCRIPTION This utility sends one or more SCSI TEST UNIT READY commands to the DEVICE. This may be useful for timing the per command overhead. Note that TEST UNIT READY has no associated data, just a 6 byte command and a returned SCSI status value. If the SCSI status value is CHECK CONDITION then most modern initiators fetch sense data from the device (i.e. autosense). This utility supports two command line syntaxes, the pre- ferred one is shown first in the synopsis and explained in this section. A later section on the old command line syntax outlines the second group of options. OPTIONS Arguments to long options are mandatory for short options as well. -h, --help print out the usage message then exit. -n, --number=NUM performs TEST UNIT READY NUM times. If not given defaults to 1. These suffix multipliers are permitted: c C *1; w W *2; b B *512; k K KiB *1,024; KB *1,000; m M MiB *1,048,576; MB *1,000,000; g G GiB *1,073,741,824; and GB *1,000,000,000 . Also a suffix of the form "x" multiplies the leading number by . Alternatively a hex number may be given, prefixed by either '0x' or has a trailing 'h'. -O, --old switch to older style options. -p, --progress show progress indication (a percentage) if available. If --number=NUM is given and NUM is greater than 1 then waits 30 seconds before subsequent checks. Exits when NUM is reached or there is no more progress indication. Ignores --time option. -t, --time after completing the requested number of TEST UNIT sg3_utils-1.23 Last change: December 2006 1 SG3_UTILS SG_TURS(8) READY commands, outputs the total duration and the average number of commands executed per second. -v, --verbose increase level or verbosity. -V, --version print version string then exit. EXIT STATUS The exit status of sg_turs is 0 when it is successful. Oth- erwise see the sg3_utils(8) man page. OLDER COMMAND LINE OPTIONS The options in this section were the only ones available prior to sg3_utils version 1.23 . In sg3_utils version 1.23 and later these older options can be selected by either set- ting the SG3_UTILS_OLD_OPTS environment variable or using '--old' (or '-O) as the first option. -n=NUM performs TEST UNIT READY NUM times. If not given defaults to 1. Equivalent to --number=NUM in the main description. -N switch to the newer style options. -p show progress indication (a percentage) if available. Equivalent to --progress in the main description. -t after completing the requested number of TEST UNIT READY commands, outputs the total duration and the average number of commands executed per second. Equivalent to --time in the main description. -v increase level of verbosity. -V print out version string then exit. AUTHORS Written by D. Gilbert COPYRIGHT Copyright O 2000-2006 Douglas Gilbert This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_inq(sg3_utils) sg3_utils-1.23 Last change: December 2006 2 SG3_UTILS SG_VERIFY(8) NAME sg_verify - invoke SCSI VERIFY command(s) on a block device SYNOPSIS sg_verify [--bpc=BPC] [--count=COUNT] [--dpo] [--help] [--lba=LBA] [--verbose] [--version] DEVICE DESCRIPTION Sends one or more SCSI VERIFY commands to DEVICE. It is the 10 byte VERIFY command defined for block devices (see SBC-2 at http://www.t10.org). Verify starts at the logical block address given by the --lba=LBA option and continues for --count=COUNT blocks. No more than --bpc=BPC blocks are ver- ified by each VERIFY command so if necessary multiple VERIFY commands are sent. No news is good news (i.e. if there are no verify errors detected no messages are sent to stderr and the Unix return status is 0). OPTIONS Arguments to long options are mandatory for short options as well. -b, --bpc=BPC where BPC specifies the maximum number of blocks that will be verified by a single SCSI VERIFY command. The default value is 128 blocks which equates to 64 KB for a disk with 512 byte blocks. If BPC is less than COUNT then multiple SCSI VERIFY commands are sent to the dev- ice. For recent block devices (disks) this value may be constrained by the maximum transfer length field in the block limits VPD page. -c, --count=COUNT where COUNT specifies the number of blocks to verify. The default value is 1 . If COUNT is greater than BPC (or its default value of 128) then multiple SCSI VERIFY commands are sent to the device. The sg_readcap utility can be used to find the maximum number of blocks that a block device (e.g. a disk) has. -d, --dpo disable page out changes the cache retention priority of blocks read on the device's cache to the lowest priority. This means that blocks read by other commands are more likely to remain in the device's cache. -h, --help output the usage message then exit. -l, --lba=LBA where LBA specifies the logical block address of the first block to start the verify operation. LBA is sg3_utils-1.23 Last change: January 2007 1 SG3_UTILS SG_VERIFY(8) assumed to be decimal unless prefixed by '0x' or a trailing 'h' (see below). The default value is 0 (i.e. the start of the device). -v, --verbose increase the level of verbosity, (i.e. debug output). -V, --version print the version string and then exit. NOTES The BPC, COUNT and LBA arguments may be followed by one of these multiplicative suffixes: c C *1; w W *2; b B *512; k K KiB *1,024; KB *1,000; m M MiB *1,048,576; MB *1,000,000; g G GiB *1,073,741,824; GB *1,000,000,000; t T TiB *(2**40); TB *(10**12); p P PiB *(2**50) and PB *(10**15). The "T" and "P" based suffixes can only be used for COUNT and LBA. Also a suffix of the form "x" multiplies the leading number by . Alternatively numerical values can be given in hexadecimal preceded by either "0x" or "0X" (or has a trailing "h" or "H"). When hex numbers are given, multipliers cannot be used. The amount of error correction and the number of retries attempted before a block is considered defective are con- trolled in part by the Verify Error Recovery mode page. A note in the SBC-2 (draft) standard advises that to minimize the number of checks (and hence have the most "sensitive" verify check) do the following in that mode page. Set the EER bit to 0, the PER bit to 1, the DTE bit to 1, the DCR bit to 1, the verify retry count to 0 and the verify error recovery timeout to 0. Mode pages can be modified with the sginfo utility. EXIT STATUS The exit status of sg_verify is 0 when it is successful. Otherwise see the sg3_utils(8) man page. AUTHORS Written by Douglas Gilbert. REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2004-2007 Douglas Gilbert This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. sg3_utils-1.23 Last change: January 2007 2 SG3_UTILS SG_VERIFY(8) SEE ALSO sginfo(sg3_utils), sg_modes(sg3_utils), sg_readcap(sg3_utils), sg_inq(sg3_utils) sg3_utils-1.23 Last change: January 2007 3 SG3_UTILS SG_VPD(8) NAME sg_vpd - fetches Vital Product Data (VPD) pages using a SCSI INQUIRY command SYNOPSIS sg_vpd [--enumerate] [--help] [--hex] [--ident] [--long] [--page=PG] [--quiet] [--raw] [--verbose] [--version] DEVICE DESCRIPTION This utility fetches a Vital Product Data page and decodes it or outputs it in ASCII hexadecimal or binary. VPD pages are fetched with a SCSI INQUIRY command. Probably the most important page is the Device Identifica- tion VPD page (page number: 0x83). Since SPC-3, support for this page has been flagged as mandatory. This page can be fetched by using the --ident option. When no options are given, other than a DEVICE, then the "Supported VPD pages" (0x0) VPD page is fetched and decoded. OPTIONS Arguments to long options are mandatory for short options as well. The options are arranged in alphabetical order based on the long option name. -e, --enumerate list the names of the known VPD pages, first the stan- dard pages, then the vendor specific pages. Each group is sorted in abbreviation order. The DEVICE and other options are ignored and this utility exits afte listing the VPD page names. -h, --help outputs the usage message summarizing command line options then exits. Ignores DEVICE if given. -H, --hex outputs the requested VPD page in ASCII hexadecimal. Can be used multiple times, see section on the ATA information vpd page. -i, --ident decode the device identification (0x83) VPD page. When used once this option has the same effect as '--page=di'. When use twice then the short form of the device identification VPD page's logical unit designa- tor is decoded. In the latter case this option has the same effect as '--quiet --page=di_lu'. -l, --long when decoding some VPD pages, give a little more sg3_utils-1.24 Last change: April 2007 1 SG3_UTILS SG_VPD(8) output. For example the ATA Information VPD page only shows the signature (in hex) and the IDENTIFY (PACKET) DEVICE (in hex) when this option is given. -p, --page=PG where PG is the VPD page to be decoded or output. The PG argument can either be an abbreviation, a number or a pair or numbers separated by a comma. The VPD page abbreviations can be seen by using the --enumerate option. If a number is given it is assumed to be decimal unless it has a hexadecimal indicator which is either a leading '0x' or a trailing 'h'. If one number is given then it is assumed to be a VPD page number. If two numbers are given the second number indicates which vendor specific VPD page to decode when several pages share the same VPD page number. If this option is not given (nor '-i', '-l' nor '-V') then the "Supported VPD pages" (0x0) VPD page is fetched and decoded. -q, --quiet suppress the amount of decoding output. -r, --raw output requested VPD page in binary. The output should be piped to a file or another utility when this option is used. The binary is sent to stdout, and errors are sent to stderr. -v, --verbose increases the level or verbosity. -V, --version print out version string then exit. ATA INFORMATION VPD PAGE This VPD page (0x89 or 'ai') is defined by the SCSI to ATA Translation standard. It contains information about the SAT layer, the "signature" of the ATA device and the response to the ATA IDENTIFY (PACKET) DEVICE command. The latter part has 512 bytes of identity, capability and settings data which the hdparm utility is capable of decoding (so this utility doesn't decode it). To unclutter the output for this page, the signature and the IDENTIFY (PACKET) DEVICE response are not output unless the --long option (or --hex or --raw) are given. When the --long option is given the IDENTIFY (PACKET) DEVICE response is output as 256 (16 bit) words as is the fashion for ATA dev- ices. To see that response as a string of bytes use the '-HH' option. To format the output suitable for hdparm to decode use either the '-HHH' or '-rr' option. For example if 'dev/sdb' is a SATA disk behind a SAT layer then this sg3_utils-1.24 Last change: April 2007 2 SG3_UTILS SG_VPD(8) command: 'sg_vpd -p ai -HHH /dev/sdb | hdparm --Istdin' should decode the ATA IDENTIFY (PACKET) DEVICE response. NOTES In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic (sg) device. In the 2.6 series block devices (e.g. disks and ATAPI DVDs) can also be specified. For example "sg_inq /dev/sda" will work in the 2.6 series kernels. From lk 2.6.6 other SCSI "char" device names may be used as well (e.g. "/dev/st0m"). EXIT STATUS The exit status of sg_vpd is 0 when it is successful. Other- wise see the sg3_utils(8) man page. AUTHOR Written by Doug Gilbert REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2006-2007 Douglas Gilbert This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_inq(sg3_utils), sdparm(sdparm), hdparm(hdparm) sg3_utils-1.24 Last change: April 2007 3 SG3_UTILS SG_WRITE_BUFFER(8) NAME sg_write_buffer - send a SCSI WRITE BUFFER command SYNOPSIS sg_write_buffer [--help] [--id=ID] [--in=FILE] [--length=LEN] [--mode=MO] [--offset=OFF] [--raw] [--skip=SKIP] [--verbose] [--version] DEVICE DESCRIPTION Sends a SCSI WRITE BUFFER command to DEVICE, along with data provided by the user. In some cases no data is required, or data can be read from the file given in the --in=FILE option, or data is read from stdin when either --raw or --in=- is given. Some WRITE BUFFER command variants do not have associated data to send to the device, for example "activate_mc" ("activate deferred microcode"). OPTIONS Arguments to long options are mandatory for short options as well. -h, --help output the usage message then exit. If used multiple times also prints the mode names and their acronyms. -i, --id=ID this option sets the buffer id field in the cdb. ID is a value between 0 (default) and 255 inclusive. -I, --in=FILE read data from file FILE that will be sent with the WRITE BUFFER command. If FILE is '-' then stdin is read until an EOF is detected (this is the same action as --raw). -l, --length=LEN where LEN is the length, in bytes, of data to be writ- ten to the device. If not given (and length cannot be deduced from --in=FILE or --raw) then defaults to zero. If the option is given and the length deduced from --in=FILE or --raw is less (or no data is provided), then bytes of 0xff are used as fill bytes. -m, --mode=MO this option sets the mode field in the cdb. MO is a value between 0 (default) and 31 inclusive. Alterna- tively an abbreviation can be given. To list the available mode abbreviations give an invalid one (e.g. '--mode=xxx') or use the '-hh' option. sg3_utils-1.23 Last change: January 2007 1 SG3_UTILS SG_WRITE_BUFFER(8) -o, --offset=OFF this option sets the buffer offset field in the cdb. OFF is a value between 0 (default) and 2**24-1 . It is a byte offset. -r, --raw read data from stdin until an EOF is detected. This data is sent with the WRITE BUFFER command to DEVICE. The action of this option is the same as using '--in=-'. -s, --skip=SKIP this option is only active when --in=FILE is given and FILE is a regular file, rather than stdin. Data is read starting at byte offset SKIP to the end of file (or the amount given by --length=LEN). If not given the byte offset defaults to 0 (i.e. the start of the file). -v, --verbose increase the level of verbosity, (i.e. debug output). -V, --version print the version string and then exit. NOTES If no --length=LEN is given this utility reads up to 8 MiB of data from the given file FILE (or stdin). If a larger amount of data is required then the --length=LEN option should be given. The user should be aware that most operat- ing systems have limits on the amount of data that can be sent with one SCSI command. In Linux this depends on the pass through mechanism used (e.g. block SG_IO or the sg driver) and various setting in sysfs in the linux lk 2.6 series (e.g. /sys/block/sda/queue/max_sectors_kb). Downloading incorrect microcode into a device has the abil- ity to render that device inoperable. One would hope that the device vendor verifies the data before activating it. If the SCSI WRITE BUFFER command is given values in its cdb (e.g. LEN) that are inappropriate (e.g. too large) then the device should respond with a sense key of ILLEGAL REQUEST and an additional sense code of INVALID FIELD in CDB. If a WRITE BUFFER command (or a sequence of them) fails due to device vendor verification checks then it should respond with a sense key of ILLEGAL REQUEST and an additional sense code of COMMAND SEQUENCE ERROR. All numbers given with options are assumed to be decimal. Alternatively numerical values can be given in hexadecimal preceded by either "0x" or "0X" (or has a trailing "h" or "H"). sg3_utils-1.23 Last change: January 2007 2 SG3_UTILS SG_WRITE_BUFFER(8) EXIT STATUS The exit status of sg_write_buffer is 0 when it is success- ful. Otherwise see the sg3_utils(8) man page. AUTHORS Written by Luben Tuikov and Douglas Gilbert. REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2006-2007 Luben Tuikov and Douglas Gilbert This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_read_buffer(sg3_utils) sg3_utils-1.23 Last change: January 2007 3 SG3_UTILS SG_WRITE_LONG(8) NAME sg_write_long - send the SCSI WRITE LONG command SYNOPSIS sg_write_long [--16] [--cor_dis] [--help] [--in=IF] [--lba=LBA] [--pblock] [--verbose] [--version] [--wr_uncor] [--xfer_len=BTL] DEVICE DESCRIPTION Send the SCSI WRITE LONG (10 or 16 byte) command to DEVICE. The buffer to be written to the DEVICE is filled with 0xff bytes or read from the IF file. This buffer includes the logical data (e.g. 512 bytes) and the ECC bytes. This utility can be used to generate a MEDIUM ERROR at a specific logical block address. This can be useful for test- ing error handling. Prior to such a test, the sg_dd utility could be used to copy the original contents of the logical block address to some safe location. After the test the sg_dd utility could be used to write back the original con- tents of the logical block address. An alternate strategy would be to read the "long" contents of the logical block address with sg_read_long utility prior to testing and restore it with this utility after testing. Take care: If recoverable errors are being injected (e.g. only one or a few bits changed so that the ECC is able to correct the data) then care should be taken with the set- tings in the "read write error recovery" mode page. Specif- ically if the ARRE (for reads) and/or AWRE (for writes) are set then recovered errors will cause the lba to be reas- signed (and the old location to be added to the grown defect list (PLIST)). This is not easily reversed and uses the (finite number) of spare sectors set aside for this purpose. If in doubt it is probably safest to clear the ARRE and AWRE bits. These bits can be checked and modified with the sdparm utility. For example: "sdparm -c AWRE,ARRE /dev/sda" will clear the bits until the disk is rebooted. OPTIONS Arguments to long options are mandatory for short options as well. -S, --16 send a SCSI WRITE LONG (16) command to DEVICE. The default action (in the absence of this option) is to send a SCSI WRITE LONG (10) command. -c, --cor_dis sets the correction disabled (i.e 'COR_DIS') bit. This inhibits various other mechanisms such as automatic block reallocation, error recovery and various sg3_utils-1.23 Last change: January 2007 1 SG3_UTILS SG_WRITE_LONG(8) informational exception conditions being triggered. This bit is new in SBC-3 . -h, --help output the usage message then exit. -i, --in=IF read data (binary) from file named IF and use it for the SCSI WRITE LONG command. If IF is "-" then stdin is read. If this option is not given then 0xff bytes are used as fill. -l, --lba=LBA where LBA is the logical block address of the sector to overwrite. Defaults to lba 0 which is a dangerous block to overwrite on a disk that is in use. Assumed to be in decimal unless prefixed with '0x' or has a tral- ing 'h'. If LBA is larger than can fit in 32 bits then the --16 option should be used. -p, --pblock sets the physical block (i.e 'PBLOCK') bit. This instructs DEVICE to use the given data (unless --wr_uncor is also given) to write to the physical block specified by LBA. The default action is to write to the logical block corresponding to the given lba. This bit is new in SBC-3 . -v, --verbose increase the degree of verbosity (debug messages). -V, --version output version string then exit. -w, --wr_uncor sets the "write uncorrected" (i.e 'WR_UNCOR') bit. This instructs the DEVICE to flag the given lba (or the phy- sical block that contains it if --pblock is also given) as having an unrecoverable error associated with it. Note: no data is transferred to DEVICE, other than the command (i.e. the cdb). The default action is to use the provided data (--xfer_len=BTL in length) and write it to DEVICE. This bit is new in SBC-3 . -x, --xfer_len=BTL where BTL is the byte transfer length (default to 520). If the given value (or the default) does not match the "long" block size of the device, nothing is written to DEVICE and the appropriate xfer_len value may be deduced from the error response which is printed (to stderr). sg3_utils-1.23 Last change: January 2007 2 SG3_UTILS SG_WRITE_LONG(8) NOTES The LBA and BTL (transfer length) arguments may be followed by the following multiplicative suffixes: c C *1; w W *2; b B *512; k K KiB *1,024; KB *1,000; m M MiB *1,048,576; MB *1,000,000; g G GiB *1,073,741,824; and GB *1,000,000,000 . Also a suffix of the form "x" multiplies the leading number by . Alternatively numerical values can be given in hexadecimal preceded by either "0x" or "0X" (or with a trailing "h" or "H"). When hex numbers are given, multipliers cannot be used. To read from a defective sector (that, for example, has been filled with 0xff bytes by this utility) use: sg_dd if=DEVICE skip=LBA of=/dev/null bs=512 count=1 To overwrite to a defective sector use: sg_dd of=DEVICE seek=LBA if=/dev/zero bs=512 count=1 This will result in a sector (block) with 512 bytes of 0x0 without a MEDIUM ERROR since the ECC and associated data will be well formed. The 10 byte SCSI WRITE LONG command limits the logical block address to a 32 bit quantity. For larger lbas use the --16 option for the SCSI WRITE LONG (16) command. EXIT STATUS The exit status of sg_write_long is 0 when it is successful. Otherwise see the sg3_utils(8) man page. AUTHORS Written by Saeed Bishara. Further work by Douglas Gilbert. REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2004-2007 Douglas Gilbert This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_read_long, sg_dd (both in sg3_utils), sdparm(sdparm) sg3_utils-1.23 Last change: January 2007 3 SG3_UTILS SG_WR_MODE(8) NAME sg_wr_mode - write mode page SYNOPSIS sg_wr_mode [--contents=H,H...] [--dbd] [--force] [--help] [--len=10|6] [--mask=M,M...] [--page=PG[,SPG]] [--save] [--verbose] [--version] DEVICE DESCRIPTION Writes a modified mode page to DEVICE. Uses the SCSI MODE SENSE (6 or 10 byte variant) command to fetch the existing mode data which includes a mode page (or subpage). It then combines that with the contents, potentially masked, and writes the modified mode page with the SCSI MODE SELECT (6 or 10 byte variant) command. This utility does not modify the block descriptor(s); if any block descriptors are fetched by the MODE SENSE command then the same block descriptors are written back with the following MODE SELECT command. If a contents argument is not given then the various com- ponents (i.e. header, block descriptor(s) and mode page) of the "current" values of the existing mode page are printed out. In this case the mode page is not altered on the dev- ice. If the contents are specified, and a mask is not specified, then the contents must match the existing mode page in vari- ous aspects unless the --force option is given. These include length, mode page code and subpage code if applica- ble. If all is well then the contents string is written to DEVICE as the new mode page. If both contents and mask strings are specified then only bit positions in the contents corresponding to set bits in the mask are taken while the existing mode page supplies bit positions corresponding to clear bits. When a mask is given then the mask and/or the contents may be shorter than the existing mode page. If the mask is shorter than the contents then the remaining bytes are taken from the contents. If the contents are shorter than the existing mode page then the remaining bytes are taken from the existing mod page. The force option allows the contents string to be written as the new mode page without any prior checks on the existing mode page. This should only be required for vendor specific mode pages. The existing mode data is ignored apart from the block descriptors which can be suppressed with the --dbd option if need be. Changing individual fields in a mode page is probably more easily done with the sdparm utility. Fields can be sg3_utils-1.23 Last change: January 2007 1 SG3_UTILS SG_WR_MODE(8) identified by acronym or by a numerical descriptor. OPTIONS Arguments to long options are mandatory for short options as well. -c, --contents=H,H... where H,H... is a string of comma separated hex numbers each of which should resolve to a byte value (i.e. 0 to ff inclusive). This is the new contents of the mode page to be written to DEVICE, potentially filtered by the mask string. -c, --contents=- reads contents string from stdin. The numbers in the string may be comma, space, tab or linefeed (newline) separated. If a line contains "#" then the remaining characters on that line are ignored. Otherwise each non separator character should resolve to a byte value (i.e. 0 to ff inclusive). This forms the new contents of the mode page to be written to DEVICE, potentially filtered by the mask string. -d, --dbd disable block descriptors (DBD flag in cdb). Some dev- ice types include block descriptors in the mode data returned by a MODE SENSE command. If so the same block descriptors are written by the MODE SELECT command. This option instructs the MODE SENSE command not to return any block descriptors. This would be a sensible default for this utility apart from the fact that not all SCSI devices support the DBD bit in the cdb. -f, --force force the contents string to be taken as the new mode page, or at least doesn't do checks on the existing mode page. Note that DEVICE may still reject the new contents for the mode page. Cannot be given with the --mask=M,M... option. -h, --hex output the usage message then exit. -l, --len=10 | 6 length of the SCSI commands (cdb) sent to DEVICE. The default is 10 so 10 byte MODE SENSE and MODE SELECT commands are issued. Some old devices don't support the 10 byte variants hence this option. -m, --mask=M,M... where M,M... is a string of comma separated hex numbers each of which should resolve to a byte value (i.e. 0 to sg3_utils-1.23 Last change: January 2007 2 SG3_UTILS SG_WR_MODE(8) ff inclusive). The mask chooses (bit by bit) whether the new mode page comes from the contents (mask bit set) or from the existing mode page (mask bit clear). If the mask string is shorter than the contents string then the remaining bytes are taken from the contents string. If the contents string is shorter than the existing mode page then the remaining bytes are taken from the existing mode page (i.e. they are left unal- tered). -p, --page=PG where PG is the page code value to fetch and modify. The page code is in hex and should be between 0 and 3e inclusive. Notice that page code 3f to fetch all mode pages is disallowed. -p, --page=PG,SPG where PG is the page code value and SPG is the subpage code value to fetch and modify. Both values are in hex. The subpage code should be between 0 and fe inclusive. Notice that subpage code ff to fetch all mode subpages (for a given mode page or all mode pages in the case of 3f,ff) is disallowed. -s, --save changes the "saved" mode page when MODE SELECT is suc- cessful. By default (i.e. when --save is not used) only the "current" mode page values are changed when MODE SELECT is successful. In this case the new mode page will stay in effect until the device is reset (e.g. power cycled). When it restarts the "saved" values for the mode page will be re-instated. So to make changes permanent use the --save option. -v, --verbose increase the level of verbosity, (i.e. debug output). -V, --version print the version string and then exit. NOTES This utility does not check whether the contents string is trying to modify parts of the mode page which are change- able. The device should do that and if some part is not changeable then it should report: "Invalid field in parame- ter list". Some mode pages are not savable. If so an attempt to use the --save option should cause an error to be reported from the device: "Illegal field in cdb". sg3_utils-1.23 Last change: January 2007 3 SG3_UTILS SG_WR_MODE(8) The device is required to do various checks before it accepts a new mode page. If these checks fail then the mode page is not altered and either a "parameter list length error" or an "invalid field in parameter list" error is returned by the device in the sense data. The recommended way to modify a mode page is to read it with a MODE SENSE, modify some part of it then write it back to the device with a MODE SELECT command. For example, reading an existing mode page can be accomplished with 'sg_modes -p=1a -r /dev/sdb > mp_1a.txt' (the power condition mode page). The mp_1a.txt file can be edited and then used as the contents string to this utility (e.g. 'sg_wr_mode -p 1a -s -c - /dev/sdb < mp_1a.txt'). Two fields differ between what is read from the device with MODE SENSE and what is written to the device with MODE SELECT: the mode data length is reserved (i.e. zero(es)) in a MODE SELECT command while the PS bit ((sub)page byte 0 bit 7) in each mode (sub)page is reserved (zero) in a MODE SELECT command. The PS bit given in the contents string is zeroed unless the --force option is selected. EXAMPLES This utility can be used together with the sg_modes utility. To re-instate the default mode page values (i.e. the mode page values chosen by the manufacturer of the device) as both the current and saved mode page values the following sequence could be used: $ sg_modes -c=2 -p=1a -r /dev/sda > t $ sg_wr_mode --page=1a --contents=- --save /dev/sda < t Next is an example of using a mask to modify the "idle con- dition counter" of the "power condition" mode page (0x1a) from 0x28 to 0x37. Note that the change is not saved so the "idle condition counter" will revert to 0x28 after the next power cycle. The output from sg_modes is abridged. $ sg_modes -p=1a /dev/hdc >> Power condition (mmc), page_control: current 00 1a 0a 00 03 00 00 00 28 00 00 01 2c $ sg_wr_mode -p 1a -c 0,0,0,0,0,0,0,37 -m 0,0,0,0,0,0,0,ff /dev/hdc $ sg_modes -p=1a /dev/hdc >> Power condition (mmc), page_control: current 00 1a 0a 00 03 00 00 00 37 00 00 01 2c EXIT STATUS The exit status of sg_wr_mode is 0 when it is successful. sg3_utils-1.23 Last change: January 2007 4 SG3_UTILS SG_WR_MODE(8) Otherwise see the sg3_utils(8) man page. AUTHORS Written by Douglas Gilbert. REPORTING BUGS Report bugs to . COPYRIGHT Copyright O 2004-2007 Douglas Gilbert This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sdparm(sdparm), sg_modes(sg3_utils), sginfo(sg3_utils) sg3_utils-1.23 Last change: January 2007 5