SG_SES(8)

NAME
sg_ses - fetch status from a SCSI Enclosure Services (SES) device

SYNOPSIS
sg_ses [--byte1=B1] [--clear=STR] [--control] [--data=H,H...] [--descriptor=DN] [--filter] [--get=STR] [--help] [--hex] [--index=IND] [--inner-hex] [--join] [--list] [--page=PG] [--raw] [--set=STR] [--status] [--verbose] [--version] DEVICE

DESCRIPTION

Fetches status from a SCSI Enclosure Service (SES) device (via a SCSI RECEIVE DIAGNOSTIC RESULTS command). This utility can also send controls to a SES device (via a SCSI SEND DIAGNOSTIC 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 is 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.

Changing the state of an enclosure (e.g. requesting the "ident" (locate) LED to flash on a disk carrier in an array) is typically done using a read-modify-write cycle. See the section on CHANGING STATE below.

The most recent reference for this utility is the draft SCSI Enclosure Services 3 document T10/2149-D Revision 3 at http://www.t10.org . Existing standards for SES and SES-2 are ANSI INCITS 305-1998 and ANSI INCITS 448-2008 respectively.

A tutorial on SES can be found here: http://www.snia.org/events/storage-developer2008/presentations/monday/RajendraDivecha_SCSI_SES.pdf . It contains both an overview and in depth information suitable for decoding the contents of some diagnostic pages used by SES.

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, --byte1=B1
    some control pages need byte 1 (i.e. the second byte) set. In the enclosure control diagnostic page byte 1 contains the INFO, NON-CRIT, CRIT and UNRECOV bits. If --control and --data=H,H... options are used then the default value is 0. If the --clear=STR, --get=STR or --set=STR option is used the default value is what was in byte 1 when the status page was read. 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. Not needed with the --clear=STR and --set=STR options.

-C, --clear=STR
    Used to clear a field in a control element. Must be used together with a --descriptor=DN or --index=IND option to specify which element is to be changed. By default the enclosure control page is modified, the only other page that can be modified is the threshold out page. See the STR FORMAT section below.

-d, --data=H,H...
    permits a string of comma separated (ASCII) hex bytes to be specified (limit 1024). A (single) space separated string of hex bytes is also allowed but the list needs to be in quotes. 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, limit 1024 bytes. Spaces, tabs and line feeds additionally are permitted as separators.

-D, --descriptor=DN
    where DN is a descriptor name (string) as found in the element descriptor diagnostic page (i.e. page 7). If that page is supported then DN may be alternative for IND (in the --index=IND option). If the descriptor name contains a space then DN needs to be surrounded by quotes (single or double) or the space escaped (e.g. preceded by a backslash). Some elements (e.g. overall elements) may not have descriptor names. Useful with the --join option as well as the --clear=STR, --get=STR and --set=STR options.

-f, --filter
    cuts down on the amount of output from the enclosure status diagnostic page and the additional element status 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.

-G, --get=STR
    Used to read a field in a status element. Must be used together with a --descriptor=DN or --index=IND option to specify which element is to be read. By default the enclosure status page is read, the only other pages that can be read are the threshold in and additional element status pages. If a value is found it is output in decimal to stdout (by default) or in hexidecimal prededed by "0x" if the --hex option is given. See the STR FORMAT section below.

-h, --help
    output the usage message then exit.

-H, --hex
    If the --get=STR option is given then output the value found (if any) in hexadecimal, with a leading "0x". Otherwise output the response in hexadecimal. Ignored with some options (e.g. --join).

-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. Implemented for the more complex diagnostic pages.

-I, --index=IND
    where IND is either an element index or an overall index (both are origin 0). If IND is between 0 and 999 then it refers to a non-overall element. If IND is between 1000 and 1999, or starts with the string 'ov' followed by 0 to 999, then it refers to an overall element. With this option 1 element will be output if an index match is found, otherwise no element is output. The default action (i.e. without this option) is to list all elements. Can be used with the enclosure status, element descriptor, threshold in and additional element status pages, plus with the --join option. See the INDEXES section below.

-j, --join
    group elements from the element descriptor, enclosure status and additional element status pages. If this option is given twice then elements from the threshold in page are also grouped. The order is dictated by the configuration page. All elements are output unless the --index=IND option is given, in which case only the matching element is output, or no element is output if there is no match. See the INDEXES section below.

-l, --list
    list all known diagnostic page names and SES elements when --list is given once. If --list is given twice, then the recognized acronyms for the --clear=STR, --get=STR and --set=STR options are listed. The utility exits after listing this information (so most other options and DEVICE are ignored).

-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 format 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.

-S, --set=STR
    Used to set a field in a control element. Must be used together with a --descriptor=DN or --index=IND option to specify which element is to be changed. By default the enclosure control page is modified, the only other page that can be modified is the threshold out page. See the STR FORMAT section below.

-v, --verbose
    increase the level of verbosity, (i.e. debug output).

-V, --version
    print the version string and then exit.

INDEXES
An enclosure can have information about its disk and tape drives plus other supporting components like power supplies spread across several diagnostic pages. Keeping this information "in sync" is relatively complicated.

The Configuration page is key: it contains a list of "type headers", each of which contains an element type (e.g. array device slot), a sub-enclosure identifier (0 for the main enclosure) and a number of possible elements. Corresponding to each type header, the enclosure status page has one "overall" element plus "number of possible elements" individual elements all of which have the given element type. For some element types the "number of possible elements" will be 0 so the enclosure status page has one "overall" element corresponding to that type header. The element descriptor page and the threshold (in and out) page follow the same pattern as the enclosure status page.

The additional element status page is a bit more complicated. It has entries for "number of possible elements" of certain element types. It does not have entries corresponding to the "overall" elements. To make the correspondence a little clearer each descriptor in this page optionally contains an "Element Index Present" indicator. If so that element index refers to the order that elements appear in the status enclosure page (and friends) starting at 0 and excluding all overall elements.

To fit in with this pattern the --index=IND option refers to one of two indexing schemes. The first is for all individual elements, excluding overall elements, starting at 0 and in the order they appear in the enclosure status page. The second indexing scheme is for overall elements only, starting at 0. If IND is a value between 0 and 999 then it refers to the individual elements. If IND is a value between 1000 and 1999, or starts with the string 'ov' followed by 0 to 999, then it refers to the overall elements.

STR FORMAT
The STR arguments of the --clear=STR, --get=STR and --set=STR options all have the same structure. There are two forms:
      <acronym>[=<value>]
      <start_byte>:<start_bit>[:<num_bits>][=<value>]

The <acronym> is one of a list of common fields (e.g. "ident" and "fault") that the utilty converts internally into the second form. The <start_byte> is usually in the range 0 to 3, the <start_bit> must be in the range 0 to 7 and the <num_bits> must be in the range 1 to 64 (default 1). The number of bits are read in the left to right sense of the element tables shown in the various SES draft documents. For example the 8 bits of byte 2 would be represented as 2:7:8 with the most significant bit being 2:7 and the LSB being 2:0 .

The <value> is optional but is ignored if provided to --get=STR. For --set=STR the default <value> is 1 while for --clear=STR the default value is 0 .

The supported list of <acronym>s can be viewed by using the --list option twice (or "-ll").

CHANGING STATE
This utility has various techniques for changing the state of a SES device. As noted above this is typically a read-modify-write type operation. Most modifiable pages have a "status" (or "in") page that can be read, and a corresponding "control" (or "out") page that can be written back to change the state of the enclosure.

The lowest level technique provided by this utility involves outputting a "status" page in hex with --raw. Then a text editor can be used to edit the hex (note: to change an enclosure control descriptor the SELECT bit needs to be set). Next the control page data can fed back with the --data=H,H... option together with the --control option; the --byte1=B1 option may need to be given as well.

Changes to the enclosure control page (and the threshold out page) can be done at a higher level. This involves choosing a page (the default in this case is the enclosure control page). Next choose an individual or overall element index (or name it with its element descriptor string). Then give the element's name (e.g. "ident" for RQST IDENT) or its position within that element (e.g. in an array device slot control element RQST IDENT is byte 2, bit 1 and 1 bit long ("2:1:1")). Finally a value can be given, if not the value for --set=STR defaults to 1 and for --clear=STR defaults to 0.

NOTES
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
These examples use Linux device names. For suitable device names in other supported Operating Systems see the sg3_utils(8) man page.

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-3 document (in revision 3: section 6.1.8) use your favourite editor to change t. The changes 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.

Fields in the various elements of the enclosure control diagnostic page can be changed with a higher level syntax. The following example looks at flashing the "ident" LED (also called "locate") on "ArrayDevice07" which is a disk (or more precisely the carrier drawer the disk is in):

   sg_ses --index=7 --set=2:1:1 /dev/sg3

If the element descriptor diagnostic page shows that "ArrayDevice07" is the descriptor name associated with element index 7 then this invocation is equivalent to the last one:

   sg_ses --descriptor=ArrayDevice07 --set=2:1:1 /dev/sg3

Further the byte 2, bit 1 (for 1 bit) field in the array slot control element is RQST INDENT for asking a disk carrier to flash a LED so it can be located. In this case "ident" (or "locate") is accepted as an acronym for that field:

   sg_ses --descriptor=ArrayDevice07 --set=ident /dev/sg3

To turn off that LED:

   sg_ses --descriptor=ArrayDevice07 --clear=ident /dev/sg3

To get the SAS address of that device (which is held in the additional element sense page (page 10)) printed on hex:

   sg_ses -p 10 -D ArrayDevice07 -G at_sas_addr -H /dev/sg3

To collate the information in the enclosure status, element descriptor and additional element status pages the --join option can be used:

   sg_ses --join /dev/sg3

This will produce a lot of output. To filter out lines that don't contain much information add the --filter option:

   sg_ses --join --filter /dev/sg3

EXIT STATUS
The exit status of sg_ses is 0 when it is successful. Otherwise see the sg3_utils(8) man page.

AUTHORS
Written by Douglas Gilbert.

REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

COPYRIGHT
Copyright © 2004-2011 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, sg3_utils (in sg3_utils package); safte-monitor (internet)