1SG_SES(8) SG3_UTILS SG_SES(8)
2
6 sg_ses - access a SCSI Enclosure Services (SES) device
7
9 sg_ses [--byte1=B1] [--clear=STR] [--control] [--data=H,H...]
10 [--descriptor=DN] [--enumerate] [--filter] [--get=STR] [--help] [--hex]
11 [--index=IIA | --index=TIA,II] [--inner-hex] [--join] [--list] [--nick‐
12 name=SEN] [--nickid=SEID] [--page=PG] [--raw] [--set=STR] [--status]
13 [--verbose] [--version] DEVICE
14
16 Fetches management information from a SCSI Enclosure Service (SES)
17 device. This utility can also modify the state of a SES device. The
18 DEVICE should be a SES device which may be a dedicated enclosure ser‐
19 vices processor in which case an INQUIRY response's Peripheral Device
20 Type is 13 [0xd]. Alternatively it may be attached to another type of
21 SCSI device (e.g. a disk) in which case the EncServ bit is set in its
22 INQUIRY response.
23 If no options are given (i.e. only the DEVICE argument is given) then
25 the names of all diagnostic pages supported are listed. Most, but not
26 necessarily all, of the named diagnostic pages are defined in the SES
27 standards and drafts. The most recent reference for this utility is the
28 draft SCSI Enclosure Services 3 document T10/2149-D Revision 6 at
29 http://www.t10.org . Existing standards for SES and SES-2 are ANSI
30 INCITS 305-1998 and ANSI INCITS 448-2008 respectively.
31 Changing the state of an enclosure (e.g. requesting the "ident"
33 (locate) LED to flash on a disk carrier in an array) is typically done
34 using a read-modify-write cycle. See the section on CHANGING STATE
35 below.
36 There is a web page discussing this utility at
38 http://sg.danny.cz/sg/sg_ses.html .
39 In the following sections "page" refers to a diagnostic page, either
41 fetched with a SCSI RECEIVE DIAGNOSTIC RESULTS command or sent to the
42 DEVICE with a SCSI SEND DIAGNOSTIC command.
43
45 Arguments to long options are mandatory for short options as well. The
46 options are arranged in alphabetical order based on the long option
47 name.
48 -b, --byte1=B1
50 some modifiable pages may need byte 1 (i.e. the second byte)
51 set. In the Enclosure Control page, byte 1 contains the INFO,
52 NON-CRIT, CRIT and UNRECOV bits. In the Subenclosure String Out,
53 Subenclosure Nickname Control and Download Microcode Control
54 pages, byte 1 is the Subenclosure identifier. Active when the
55 --control and --data=H,H... options are used and the default
56 value is 0. If the --clear=STR or --set=STR option is used then
57 the value read from byte 1 is written back to byte 1. B1 is in
58 decimal unless it is prefixed by '0x' or '0X' (or has a trailing
59 'h' or 'H').
60 -C, --clear=STR
62 Used to clear an element field in the Enclosure Control or
63 Threshold Out page. Must be used together with a --descriptor=DN
64 or --index=... option to specify which element is to be changed.
65 The Enclosure Control page is assumed if the --page=PG option is
66 not given. See the STR FORMAT section below.
67 -c, --control
69 will send control information to the DEVICE via a SCSI SEND
70 DIAGNOSTIC command. Cannot give both this option and --status.
71 The Enclosure Control, String Out, Threshold Out, Array Control
72 (obsolete in SES-2), Subenclosure String Out, Subenclosure Nick‐
73 name Control and Download Microcode pages can be set currently.
74 This option is assumed if either the --clear=STR or --set=STR
75 option is given.
76 -d, --data=H,H...
78 permits a string of comma separated (ASCII) hex bytes to be
79 specified (limit 1024). A (single) space separated string of hex
80 bytes is also allowed but the list needs to be in quotes. This
81 option allows the parameters to a control page to be specified.
82 The string given should not include the first 4 bytes (i.e. page
83 code and length).
84 -d, --data=-
86 reads a data string from stdin, limit 1024 bytes. stdin may pro‐
87 vide ASCII hex as a comma separated list (i.e. as with the
88 --data=H,H... option). Additionally spaces, tabs and line
89 feeds are permitted as separators from stdin . Stops reading
90 stdin when an EOF is detected.
91 -D, --descriptor=DN
93 where DN is a descriptor name (string) as found in the Element
94 Descriptor page. If that page is supported then DN may be an
95 alternative for TIA,II (in the --index=TIA,II option). If the
96 descriptor name contains a space then DN needs to be surrounded
97 by quotes (single or double) or the space escaped (e.g. preceded
98 by a backslash). Some elements (e.g. overall elements) may not
99 have descriptor names. Useful with the --clear=STR, --get=STR
100 and --set=STR options. If no other options are given then the
101 --join option is assumed.
102 -e, --enumerate
104 enumerate all known page names and SES elements when this option
105 is given once. If --enumerate is given twice, then the recog‐
106 nised acronyms for the --clear=STR, --get=STR and --set=STR
107 options are listed. The utility exits after listing this infor‐
108 mation (so most other options and DEVICE are ignored).
109 -f, --filter
111 cuts down on the amount of output from the Enclosure Status page
112 and the Additional Element Status page. When this option is
113 given, any line which has all its binary flags cleared (i.e. 0)
114 is filtered out (i.e. ignored). If a line has some other value
115 on it (e.g. a temperature) then it is output. The --filter
116 option is also useful for reducing the amount of output gener‐
117 ated by the --join option.
118 -G, --get=STR
120 Used to read a field in a status element. Must be used together
121 with a --descriptor=DN or --index=... option to specify which
122 element is to be read. By default the Enclosure Status page is
123 read, the only other pages that can be read are the Threshold In
124 and Additional Element Status pages. If a value is found it is
125 output in decimal to stdout (by default) or in hexadecimal pre‐
126 ceded by "0x" if the --hex option is also given. See the STR
127 FORMAT section below.
128 -h, --help
130 output the usage message then exit.
131 -H, --hex
133 If the --get=STR option is given then output the value found (if
134 any) in hexadecimal, with a leading "0x". Otherwise output the
135 response in hexadecimal. Ignored with some options (e.g.
136 --join).
137 -I, --index=IIA
139 where IIA is either an individual index (II) or an Element type
140 abbreviation (A). See the INDEXES section below. If the
141 --page=PG option is not given then the Enclosure Status (or Con‐
142 trol) page is assumed. May be used with the --join option or
143 one of the --clear=STR, --get=STR or --set=STR options. To enu‐
144 merate the available Element type abbreviations use the --enu‐
145 merate option.
146 -I, --index=TIA,II
148 where TIA,II is an type header index (TI) or Element type abbre‐
149 viation (A) followed by an individual index (II). See the
150 INDEXES section below. If the --page=PG option is not given then
151 the Enclosure Status (or Control) page is assumed. May be used
152 with the --join option or one of the --clear=STR, --get=STR or
153 --set=STR options. To enumerate the available Element type
154 abbreviations use the --enumerate option.
155 -i, --inner-hex
157 the outer levels of a status page are decoded and printed out
158 but the innermost level (e.g. the Element Status Descriptor) is
159 output in hex. Also active with the Additional Element Status
160 and Threshold In pages. Can be used with --index=... and/or
161 --join options.
162 -j, --join
164 group elements from the Element Descriptor, Enclosure Status and
165 Additional Element Status pages. If this option is given twice
166 then elements from the Threshold In page are also grouped. The
167 order is dictated by the Configuration page. All elements are
168 output unless the --index= or --descriptor=DN option is given,
169 in which case only the matching element is output. The --filter
170 option can be added to reduce the amount of output generated by
171 the option. See the INDEXES section below.
172 -l, --list
174 This option is equivalent to --enumerate. See that option.
175 -n, --nickname=SEN
177 where SEN is the new Subenclosure Nickname. Only the first 32
178 characters (bytes) of SEN are used, if more are given they are
179 ignored. See the SETTING SUBENCLOSURE NICKNAME section below.
180 -N, --nickid=SEID
182 where SEID is the Subenclosure identifier that the new Nickname
183 (SEN) will be applied to. The default value is 0 which is the
184 main enclosure.
185 -p, --page=PG
187 where PG is a page abbreviation or code (a number). If PG starts
188 with a digit it is assumed to be in decimal unless prefixed by
189 0x for hex. Valid range is 0 to 255 (0x0 to 0xff) inclusive.
190 Default is page 'sdp' which is page_code 0 (i.e. "Supported
191 Diagnostic Pages") if no other options are given.
192 -r, --raw
194 outputs the chosen status page in ASCII hex in a format suitable
195 for a later invocation using the --data= option. A page less its
196 first 4 bytes (page code and length) is output. When used twice
197 (e.g. -rr) the full page contents is output in binary to stdout.
198 -S, --set=STR
200 Used to set an element field in the Enclosure Control or Thresh‐
201 old Out page. Must be used together with a --descriptor=DN or
202 --index=... option to specify which element is to be changed.
203 The Enclosure Control page is assumed if the --page=PG option is
204 not given. See the STR FORMAT section below.
205 -s, --status
207 will fetch page from the DEVICE via a SCSI RECEIVE DIAGNOSTIC
208 RESULTS command. In the absence of other options that imply mod‐
209 ifying a page (e.g. --control or --set=STR) then --status is
210 assumed.
211 -v, --verbose
213 increase the level of verbosity, (i.e. debug output).
214 -V, --version
216 print the version string and then exit.
217
219 An enclosure can have information about its disk and tape drives plus
220 other supporting components like power supplies spread across several
221 pages. Addressing a specific element (overall or individual) is com‐
222 plicated.
223 The Configuration page is key: it contains a list of "type headers",
225 each of which contains an Element type (e.g. Array Device Slot), a
226 Subenclosure identifier (0 for the primary enclosure) and a "Number of
227 possible elements". Corresponding to each type header, the Enclosure
228 Status page has one "overall" element plus "Number of possible ele‐
229 ments" individual elements all of which have the given Element type.
230 For some Element types the "Number of possible elements" will be 0 so
231 the Enclosure Status page has only one "overall" element corresponding
232 to that type header. The Element Descriptor page and the Threshold (In
233 and Out) pages follow the same pattern as the Enclosure Status page.
234 The Additional Element Status page is a bit more complicated. It has
236 entries for "Number of possible elements" of certain Element types. It
237 does not have entries corresponding to the "overall" elements. To make
238 the correspondence a little clearer each descriptor in this page
239 optionally contains an "Element Index Present" (EIP) indicator. If EIP
240 is set then each element's "Element Index" field refers to the position
241 of the corresponding element in the Enclosure Status page.
242 Addressing a single overall element or a single individual element is
244 done with two indexes: TI and II. Both are origin 0. TI=0 corresponds
245 to the first type header entry which must be a Device Slot or Array
246 Device Slot Element type (according to the SES-2 standard). To address
247 the corresponding overall instance, II is set to -1, otherwise II can
248 be set to the individual instance index. As an alternative to the type
249 header index (TI), an Element type abbreviation (A) optionally followed
250 by a number (e.g. "ps" refers to the first Power Supply Element type;
251 "ps1" refers to the second) can be given.
252 One of two command lines variants can be used to specify indexes:
254 --index=TIA,II where TIA is either an type header index (TI) or an Ele‐
255 ment type abbreviation (A) (e.g. "ps" or "ps1"). II is either an indi‐
256 vidual index or "-1" to specify the overall element. The second variant
257 is --index=IIA where IIA is either an individual index (II) or an Ele‐
258 ment type abbreviation (A). When IIA is an individual index then the
259 option is equivalent to --index=0,II. When IIA is an Element type
260 abbreviation then the option is equivalent to --index=A,-1.
261 To cope with vendor specific Element types (which should be in the
263 range 128 to 255) the Element type can be given as a number with a
264 leading underscore. For example these are equivalent: --index=arr and
265 --index=_23 since the Array Device Slot Element type value is 23. Also
266 --index=ps1 and --index=_2_1 are equivalent.
267 Another example: if the first type header in the Configuration page has
269 Array Device Slot Element type then --index=0,-1 is equivalent to
270 --index=arr. Also --index=arr,3 is equivalent to --index=3.
271 Note that if the Element Descriptor page is available then the
273 --descriptor=DN option may be an alternative to the --index=... option.
274
276 The STR operands of the --clear=STR, --get=STR and --set=STR options
277 all have the same structure. There are two forms:
278 <acronym>[=<value>]
279 <start_byte>:<start_bit>[:<num_bits>][=<value>]
280 The <acronym> is one of a list of common fields (e.g. "ident" and
282 "fault") that the utility converts internally into the second form. The
283 <start_byte> is usually in the range 0 to 3, the <start_bit> must be in
284 the range 0 to 7 and the <num_bits> must be in the range 1 to 64
285 (default 1). The number of bits are read in the left to right sense of
286 the element tables shown in the various SES draft documents. For exam‐
287 ple the 8 bits of byte 2 would be represented as 2:7:8 with the most
288 significant bit being 2:7 and the least sugnificant bit being 2:0 .
289 The <value> is optional but is ignored if provided to --get=STR. For
291 --set=STR the default <value> is 1 while for --clear=STR the default
292 value is 0 .
293 The supported list of <acronym>s can be viewed by using the --enumerate
295 option twice (or "-ee").
296
298 This utility has various techniques for changing the state of a SES
299 device. As noted above this is typically a read-modify-write type
300 operation. Most modifiable pages have a "status" (or "in") page that
301 can be read, and a corresponding "control" (or "out") page that can be
302 written back to change the state of the enclosure.
303 The lower level technique provided by this utility involves outputting
305 a "status" page in hex with --raw. Then a text editor can be used to
306 edit the hex (note: to change an Enclosure Control descriptor the
307 SELECT bit needs to be set). Next the control page data can fed back
308 with the --data=H,H... option together with the --control option; the
309 --byte1=B1 option may need to be given as well.
310 Changes to the Enclosure Control page (and the Threshold Out page) can
312 be done at a higher level. This involves choosing a page (the default
313 in this case is the Enclosure Control page). Next choose an individual
314 or overall element index (or name it with its Element Descriptor
315 string). Then give the element's name (e.g. "ident" for RQST IDENT) or
316 its position within that element (e.g. in an Array Device Slot Control
317 element RQST IDENT is byte 2, bit 1 and 1 bit long ("2:1:1")). Finally
318 a value can be given, if not the value for --set=STR defaults to 1 and
319 for --clear=STR defaults to 0.
320
322 The format of the Subenclosure Nickname control page is different from
323 its corresponding status page. The status page reports all Subenclosure
324 Nicknames (and Subenclosure identifier 0 is the main enclosure) while
325 the control page allows only one of them to be changed. Therefore using
326 the --data option technique to change a Subenclosure nickname is diffi‐
327 cult (but still possible).
328 To simplify changing a Subenclosure nickname the --nickname=SEN and
330 --nickid=SEID options have been added. If the SEN string contains spa‐
331 ces or other punctuation, it should be quoted: surrounded by single or
332 double quotes (or the offending characters escaped). If the
333 --nickid=SEID is not given then a Subenclosure identifier of 0 is
334 assumed. As a guard the --control option must also be given. If the
335 --page=PG option is not given then --page=snic is assumed.
336 When --nickname=SEN is given then the Subenclosure Nickname Status page
338 is read to obtain the Generation Code field. That Generation Code
339 together with no more than 32 bytes from the Nickname (SEN) and the
340 Subenclosure Identifier (SEID) are written to the Subenclosure Nickname
341 Control page.
342 There is an example of changing a nickname in the EXAMPLES section
344 below.
345
347 This utility can be used to fetch arbitrary (i.e. non SES) diagnostic
348 pages (using the SCSI READ DIAGNOSTIC command). To this end the
349 --page=PG and --hex options would be appropriate. Arbitrary diagnostic
350 pages can be sent to a device with the sg_senddiag utility.
351 The most troublesome part of the join operation is associating Addi‐
353 tional Element Status descriptors correctly. At least one SES device
354 vendor has misinterpreted the SES-2 standard with its "element index"
355 field. The code in this utility interprets the "element index" field as
356 per the SES-2 standard and if that yields an inappropriate Element
357 type, adjusts its indexing to follow that vendor's misinterpretation.
358 In draft SES-3 revision 5 the "Door Lock" element name was changed to
360 the "Door" (and an OPEN field was added to the status element). As a
361 consequence the former 'dl' element type abbreviation has been changed
362 to 'do'.
363 There is a related command set called SAF-TE (SCSI attached fault-tol‐
365 erant enclosure) for enclosure (including RAID) status and control.
366 SCSI devices that support SAF-TE report "Processor" peripheral device
367 type (0x3) in their INQUIRY response. See the sg_safte utility in this
368 package or safte-monitor on the Internet.
369
371 These examples use Linux device names. For suitable device names in
372 other supported Operating Systems see the sg3_utils(8) man page.
373 To view the supported pages:
375 sg_ses /dev/bsg/6:0:2:0
377 To view the Configuration page:
379 sg_ses --page=cf /dev/bsg/6:0:2:0
381 To view the Enclosure Status page:
383 sg_ses --page=es /dev/bsg/6:0:2:0
385 To get the (attached) SAS address of that device (which is held in the
387 Additional Element Sense page (page 10)) printed on hex:
388 sg_ses -p aes -D ArrayDevice07 -G at_sas_addr -H /dev/sg3
390 To collate the information in the Enclosure Status, Element Descriptor
392 and Additional Element Status pages the --join option can be used:
393 sg_ses --join /dev/sg3
395 This will produce a lot of output. To filter out lines that don't con‐
397 tain much information add the --filter option:
398 sg_ses --join --filter /dev/sg3
400 Fields in the various elements of the Enclosure Control and Threshold
402 pages can be changed with the --clear=STR and --set=STR options. [All
403 modifiable pages can be changed with the --raw and --data=H,H...
404 options.] The following example looks at making the "ident" LED (also
405 called "locate") flash on "ArrayDevice07" which is a disk (or more pre‐
406 cisely the carrier drawer the disk is in):
407 sg_ses --index=7 --set=2:1:1 /dev/sg3
409 If the Element Descriptor diagnostic page shows that "ArrayDevice07" is
411 the descriptor name associated with element index 7 then this invoca‐
412 tion is equivalent to the previous one:
413 sg_ses --descriptor=ArrayDevice07 --set=2:1:1 /dev/sg3
415 Further the byte 2, bit 1 (for 1 bit) field in the Array Device Slot
417 Control element is RQST IDENT for asking a disk carrier to flash a LED
418 so it can be located. In this case "ident" (or "locate") is accepted as
419 an acronym for that field:
420 sg_ses --descriptor=ArrayDevice07 --set=ident /dev/sg3
422 To stop that LED flashing:
424 sg_ses --descriptor=ArrayDevice07 --clear=ident /dev/sg3
426 Now for an example of a more general but lower level technique for
428 changing a modifiable diagnostic page. The String (In and Out) diagnos‐
429 tics page is relatively simple (compared with the Enclosure Status/Con‐
430 trol page). However the use of this lower level technique is awkward
431 involving three steps: read, modify then write. First check the current
432 String (In) page contents:
433 sg_ses --page=str /dev/bsg/6:0:2:0
435 Now the "read" step. The following command will send the contents of
437 the String page (from byte 4 onwards) to stdout. The output will be in
438 ASCII hex with pairs of hex digits representing a byte, 16 pairs per
439 line, space separated. The redirection puts stdout in a file called
440 "t":
441 sg_ses --page=str --raw /dev/bsg/6:0:2:0 > t
443 Then with the aid of the SES-3 document (in revision 3: section 6.1.6)
445 use your favourite editor to change t. The changes can be sent to the
446 device with:
447 sg_ses --page=str --control --data=- /dev/bsg/6:0:2:0 < t
449 If the above is successful, the String page should have been changed.
451 To check try:
452 sg_ses --page=str /dev/bsg/6:0:2:0
454 To change the nickname on the main enclosure:
456 sg_ses --nickname='1st enclosure' --control /dev/bsg/6:0:2:0
458
460 The exit status of sg_ses is 0 when it is successful. Otherwise see the
461 sg3_utils(8) man page.
462
464 Written by Douglas Gilbert.
465
467 Report bugs to <dgilbert at interlog dot com>.
468
470 Copyright © 2004-2013 Douglas Gilbert
471 This software is distributed under a FreeBSD license. There is NO war‐
472 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
473 POSE.
474
476 sg_inq, sg_safte, sg_senddiag, sg3_utils (in sg3_utils package);
477 safte-monitor (Internet)
478sg3_utils-1.37 September 2013 SG_SES(8)