Content-type: text/html
Fetches management information from a SCSI Enclosure Service (SES) device. This utility can also modify the state of a SES device. The DEVICE should be a SES device which may be a dedicated enclosure services processor in which case an INQUIRY response's Peripheral Device Type is 13 [0xd]. Alternatively it may be 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 (i.e. only the DEVICE argument is given) then the names of all diagnostic pages supported are listed. Most, but not necessarily all, of the named diagnostic pages are defined in the SES standards and drafts. 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.
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.
There is a web page discussing this utility at http://sg.danny.cz/sg/sg_ses.html .
In the following sections "page" refers to a diagnostic page, either fetched with a SCSI RECEIVE DIAGNOSTIC RESULTS command or sent to the DEVICE with a SCSI SEND DIAGNOSTIC command.
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 Subenclosure identifier (0 for the primary 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 only one "overall" element corresponding to that type header. The Element Descriptor page and the Threshold (In and Out) pages 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" (EIP) indicator. If EIP is set then each element's "Element Index" field refers to the position of the corresponding element in the Enclosure Status page.
Addressing a single overall element or a single individual element is done with two indexes: TI and II. Both are origin 0. TI=0 corresponds to the first type header entry which must be a Device Slot or Array Device Slot Element type (according to the SES-2 standard). To address the corresponding overall instance, II is set to -1, otherwise II can be set to the individual instance index. As an alternative to the type header index (TI), an Element type abbreviation (A) optionally followed by a number (e.g. "ps" refers to the first Power Supply Element type; "ps1" refers to the second) can be given.
One of two command lines variants can be used to specify indexes: --index=TIA,II where TIA is either an type header index (TI) or an Element type abbreviation (A) (e.g. "ps" or "ps1"). II is is either an individual index or "-1" to specify the overall element. The second variant is --index=IIA where IIA is either an individual index (II) or an Element type abbreviation (A). When IIA is an individual index then the option is equivalent to --index=0,II. When IIA is an Element type abbreviation then the option is equivalent to --index=A,-1.
To cope with vendor specific Element types (which should be in the range 128 to 255) the Element type can be given as a number with a leading underscore. For example these are equivalent: --index=arr and --index=_23 since the Array Device Slot Element type value is 23. Also --index=ps1 and --index=_2_1 are equivalent.
Another example: if the first type header in the Configuration page has Array Device Slot Element type then --index=0,-1 is equivalent to --index=arr. Also --index=arr,3 is equivalent to --index=3.
Note that if the Element Descriptor page is available then the --descriptor=DN option may be an alternative to the --index=... option.
The <acronym> is one of a list of common fields (e.g. "ident" and "fault") that the utility 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 least sugnificant bit 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 --enumerate option twice (or "-ee").
The lower 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.
The most troublesome part of the join operation is associating Additional Element Status descriptors correctly. At least one SES device vendor has misinterpreted the SES-2 standard with its "element index" field. The code in this utility interprets the "element index" field as per the SES-2 standard and if that yields an inappropriate Element type, adjusts its indexing to follow that vendor's misinterpretation.
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.
To view the supported pages:
sg_ses /dev/bsg/6:0:2:0
To view the Configuration page:
sg_ses --page=cf /dev/bsg/6:0:2:0
To view the Enclosure Status page:
sg_ses --page=es /dev/bsg/6:0:2:0
To get the (attached) SAS address of that device (which is held in the Additional Element Sense page (page 10)) printed on hex:
sg_ses -p aes -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
Fields in the various elements of the Enclosure Control and Threshold pages can be changed with the --clear=STR and --set=STR options. [All modifiable pages can be changed with the --raw and --data=H,H... options.] The following example looks at making the "ident" LED (also called "locate") flash 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 previous one:
sg_ses --descriptor=ArrayDevice07 --set=2:1:1 /dev/sg3
Further the byte 2, bit 1 (for 1 bit) field in the Array Device Slot Control element is RQST IDENT 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 stop that LED flashing:
sg_ses --descriptor=ArrayDevice07 --clear=ident /dev/sg3
Now for an example of a more general but lower level technique for changing a modifiable diagnostic page. The String (In and Out) diagnostics page is relatively simple (compared with the Enclosure Status/Control page). However the use of this lower level technique is awkward involving three steps: read, modify then write. First check the current String (In) page contents:
sg_ses --page=str /dev/bsg/6:0:2:0
Now the "read" step. The following command will send the contents of the String page (from byte 4 onwards) to stdout. The output will be in ASCII hex with pairs of hex digits representing a byte, 16 pairs per line, space separated. The redirection puts stdout in a file called "t":
sg_ses --page=str --raw /dev/bsg/6:0:2:0 > t
Then with the aid of the SES-3 document (in revision 3: section 6.1.6) use your favourite editor to change t. The changes can be sent to the device with:
sg_ses --page=str --control --data=- /dev/bsg/6:0:2:0 < t
If the above is successful, the String page should have been changed. To check try:
sg_ses --page=str /dev/bsg/6:0:2:0