1SG_SES(8) SG3_UTILS SG_SES(8)
2
3
4
6 sg_ses - access a SCSI Enclosure Services (SES) device
7
9 sg_ses [--all] [--descriptor=DES] [--dev-slot-num=SN] [--eiioe=A_F]
10 [--filter] [--get=STR] [--hex] [--index=IIA | --index=TIA,II] [--in‐
11 ner-hex] [--join] [--maxlen=LEN] [--page=PG] [--quiet] [--raw] [--read‐
12 only] [--sas-addr=SA] [--status] [--verbose] [--warn] DEVICE
13
14 sg_ses --control [--byte1=B1] [--clear=STR] [--data=H,H...]
15 [--data=@FN] [--descriptor=DES] [--dev-slot-num=SN] [--index=IIA |
16 --index=TIA,II] [--mask] [--maxlen=LEN] [--nickname=SEN]
17 [--nickid=SEID] [--page=PG] [--readonly] [--sas-addr=SA] [--set=STR]
18 [--verbose] DEVICE
19
20 sg_ses --data=@FN --status [--raw --raw] [<all options from first
21 form>]
22 sg_ses --inhex=FN --status [--raw --raw] [<all options from first
23 form>]
24
25 sg_ses [--enumerate] [--index=IIA] [--list] [--help] [--version]
26
28 Fetches management information from a SCSI Enclosure Service (SES) de‐
29 vice. This utility can also modify the state of a SES device. The DE‐
30 VICE should be a SES device which may be a dedicated enclosure services
31 processor in which case an INQUIRY response's Peripheral Device Type is
32 13 [0xd]. Alternatively it may be attached to another type of SCSI de‐
33 vice (e.g. a disk) in which case the EncServ bit is set in its INQUIRY
34 response.
35
36 If the DEVICE argument is given with no options then the names of all
37 diagnostic pages (dpages) supported are listed. Most, but not necessar‐
38 ily all, of the named dpages are defined in the SES standards and
39 drafts. The most recent reference for this utility is the draft SCSI
40 Enclosure Services 4 document T10/BSR INCITS 555 Revision 5 at
41 http://www.t10.org . Existing standards for SES, SES-2 and SES-3 are
42 ANSI INCITS 305-1998 and ANSI INCITS 448-2008 and ANSI INCITS 518-2017
43 respectively.
44
45 The first form shown in the synopsis is for fetching and decoding
46 dpages or fields from the SES DEVICE. A SCSI RECEIVE DIAGNOSTIC RESULTS
47 command is sent to the DEVICE to obtain each dpage response. Rather
48 than decoding a fetched dpage, it may be output in hex or binary with
49 the --hex or --raw --raw options.
50
51 The second form in the synopsis is for modifying dpages or fields held
52 in the SES DEVICE. A SCSI SEND DIAGNOSTIC command containing a "con‐
53 trol" dpage is sent to the DEVICE to cause changes. Changing the state
54 of an enclosure (e.g. requesting the "ident" (locate) LED to flash on a
55 disk carrier in an array) is typically done using a read-modify-write
56 cycle. See the section on CHANGING STATE below.
57
58 The third form in the synopsis has two equivalent invocations shown.
59 They decode the contents of a file (named FN) that holds a hexadecimal
60 or binary representation of one, or many, SES dpage responses. Typi‐
61 cally an earlier invocation of the first form of this utility with the
62 '-HHHH' option would have generated that file. Since no SCSI commands
63 are sent, the DEVICE argument if given will be ignored.
64
65 The last form in the synopsis shows the options for providing command
66 line help (i.e. usage information), listing out dpage and field infor‐
67 mation tables held by the utility (--enumerate), or printing the ver‐
68 sion string of this utility.
69
70 There is a web page discussing this utility at
71 http://sg.danny.cz/sg/sg_ses.html . Support for downloading microcode
72 to a SES device has been placed in a separate utility called sg_ses_mi‐
73 crocode.
74
75 In the following sections "dpage" refers to a diagnostic page, either
76 fetched with a SCSI RECEIVE DIAGNOSTIC RESULTS command, sent to the DE‐
77 VICE with a SCSI SEND DIAGNOSTIC command, or fetched from data supplied
78 by the --data= option.
79
81 Arguments to long options are mandatory for short options as well. The
82 options are arranged in alphabetical order based on the long option
83 name.
84
85 -a, --all
86 shows (almost) all status dpages, following references and pre‐
87 senting the information as a long list whose indentation indi‐
88 cates the level of nesting. This option is actually the same as
89 --join, see its description for more information.
90
91 -b, --byte1=B1
92 some modifiable dpages may need byte 1 (i.e. the second byte)
93 set. In the Enclosure Control dpage, byte 1 contains the INFO,
94 NON-CRIT, CRIT and UNRECOV bits. In the Subenclosure String Out,
95 Subenclosure Nickname Control and Download Microcode Control
96 dpages, byte 1 is the Subenclosure identifier. Active when the
97 --control and --data=H,H... options are used and the default
98 value is 0. If the --clear=STR or --set=STR option is used then
99 the value read from byte 1 is written back to byte 1. B1 is in
100 decimal unless it is prefixed by '0x' or '0X' (or has a trailing
101 'h' or 'H').
102
103 -C, --clear=STR
104 Used to clear an element field in the Enclosure Control or
105 Threshold Out dpage. Must be used together with an indexing op‐
106 tion to specify which element is to be changed. The Enclosure
107 Control dpage is assumed if the --page=PG option is not given.
108 See the STR FORMAT and the CLEAR, GET, SET sections below.
109
110 -c, --control
111 will send control information to the DEVICE via a SCSI SEND DI‐
112 AGNOSTIC command. Cannot give both this option and --status.
113 The Enclosure Control, String Out, Threshold Out, Array Control
114 (obsolete in SES-2), Subenclosure String Out, Subenclosure Nick‐
115 name Control and Download Microcode dpages can be set currently.
116 This option is assumed if either the --clear=STR or --set=STR
117 option is given.
118
119 -d, --data=H,H...
120 permits a string of comma separated (ASCII) hex bytes to be
121 specified (limit 1024). A (single) space separated string of hex
122 bytes is also allowed but the list needs to be in quotes. This
123 option allows the parameters to a control dpage to be specified.
124 The string given should not include the first 4 bytes (i.e. page
125 code and length). See the DATA SUPPLIED section below.
126
127 -d, --data=-
128 reads one or more data strings from stdin, limit almost 2**16
129 bytes. stdin may provide ASCII hex as a comma separated list
130 (i.e. as with the --data=H,H... option). Additionally spaces,
131 tabs and line feeds are permitted as separators from stdin .
132 Stops reading stdin when an EOF is detected. See the DATA SUP‐
133 PLIED section below.
134
135 -d, --data=@FN
136 reads one or more data strings from the file called FN, limit
137 almost 2**16 bytes. The contents of the file is decoded in the
138 same fashion as stdin described in the previous option. See the
139 DATA SUPPLIED section below.
140
141 -D, --descriptor=DES
142 where DES is a descriptor name (string) as found in the Element
143 Descriptor dpage. This is a medium level indexing alternative to
144 the low level --index= options. If the descriptor name contains
145 a space then DES needs to be surrounded by quotes (single or
146 double) or the space escaped (e.g. preceded by a backslash). See
147 the DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS section
148 below.
149
150 -x, --dev-slot-num=SN, --dsn=SN
151 where SN is a device slot number found in the Additional Element
152 Status dpage. Only entries for FCP and SAS devices (with EIP=1)
153 have device slot numbers. SN must be a number in the range 0 to
154 255 (inclusive). 255 is used to indicate there is no correspond‐
155 ing device slot. This is a medium level indexing alternative to
156 the low level --index= options. See the DESCRIPTOR NAME, DEVICE
157 SLOT NUMBER AND SAS ADDRESS section below.
158
159 -E, --eiioe=A_F
160 A_F is either the string 'auto' or 'force'. There was some
161 fuzziness in the interpretation of the 'element index' field in
162 the Additional Element Status (AES) dpage between SES-2 and
163 SES-3. The EIIOE bit was introduced to resolve the problem but
164 not all enclosures have caught up. In the SES-3 revision 12
165 draft the EIIOE bit was expanded to a 2 bit EIIOE field. Using
166 '--eiioe=force' will decode the AES dpage as if the EIIOE field
167 is set to 1. Using '--eiioe=auto' will decode the AES dpage as
168 if the EIIOE field is set to 1 if the first AES descriptor has
169 its EIP bit set and its element index field is 1 (in other words
170 a heuristic to guess whether the EIIOE field should be set to 1
171 or 0).
172 If the enclosure sets the actual EIIOE field to 1 or more then
173 this option has no effect. It is recommended that HP JBOD users
174 set --eiioe=auto .
175
176 -e, --enumerate
177 enumerate all known diagnostic page (dpage) names and SES ele‐
178 ments that this utility recognizes plus the abbreviations ac‐
179 cepted by this utility. Ignores DEVICE if it is given. Essen‐
180 tially it is dumping out tables held internally by this utility.
181 If --enumerate is given twice, then the recognised acronyms for
182 the --clear=STR, --get=STR and --set=STR options are listed. The
183 utility exits after listing this information, so most other op‐
184 tions and DEVICE are ignored. Since there are many acronyms for
185 the Enclosure Control/Status dpage then the output can be fur‐
186 ther restricted by giving the --index=IIA option (e.g. "sg_ses
187 -ee -I ts" to only show the acronyms associated with the Enclo‐
188 sure Control/Status dpage's Temperature Sensor Element Type).
189
190 -f, --filter
191 cuts down on the amount of output from the Enclosure Status
192 dpage and the Additional Element Status dpage. When this option
193 is given, any line which has all its binary flags cleared (i.e.
194 0) is filtered out (i.e. ignored). If a line has some other
195 value on it (e.g. a temperature) then it is output. When this
196 option is used twice only elements associated with the "sta‐
197 tus=ok" field (in the Enclosure status dpage) are output. The
198 --filter option is useful for reducing the amount of output gen‐
199 erated by the --join option.
200
201 -G, --get=STR
202 Used to read a field in a status element. Must be used together
203 with a an indexing option to specify which element is to be
204 read. By default the Enclosure Status dpage is read, the only
205 other dpages that can be read are the Threshold In and Addi‐
206 tional Element Status dpages. If a value is found it is output
207 in decimal to stdout (by default) or in hexadecimal preceded by
208 "0x" if the --hex option is also given. See the STR FORMAT and
209 the CLEAR, GET, SET sections below.
210
211 -h, --help
212 output the usage message then exit. Since there is a lot of in‐
213 formation, it is split into two pages. The most important is
214 shown on the first page. Use this option twice (e.g. '-hh') to
215 output the second page. Note: the --enumerate option might also
216 be viewed as a help or usage type option. And like this option
217 it has a "given twice" form: '-ee'.
218
219 -H, --hex
220 If the --get=STR option is given then output the value found (if
221 any) in hexadecimal, with a leading "0x". Otherwise output the
222 response in hexadecimal; with trailing ASCII if given once,
223 without it if given twice, and simple hex if given three or more
224 times. Ignored when all elements from several dpages are being
225 accessed (e.g. when the --join option is used). Also see the
226 --raw option which may be used with this option.
227 To dump one of more dpage responses to stdout in ASCII parsable
228 hexadecimal use -HHH or -HHHH. The triple H form only outputs
229 hexadecimals which is fine for a single dpage response. When all
230 dpages are dumped (e.g. with --page=all) then the quad H form
231 adds the name of each dpage following a hash mark ('#'). The
232 --data= option parser ignores everything from and including a
233 hash mark to the end of the line. Hence the output of the quad H
234 form is still parsable plus it is easier for users to view and
235 possibly edit. -HHHHH (that is 5) adds the page code in hex af‐
236 ter the page's name in the comment.
237
238 -I, --index=IIA
239 where IIA is either an individual index (II) or an Element type
240 abbreviation (A). See the INDEXES section below. If the
241 --page=PG option is not given then the Enclosure Status (or Con‐
242 trol) dpage is assumed. May be used with the --join option or
243 one of the --clear=STR, --get=STR or --set=STR options. To enu‐
244 merate the available Element type abbreviations use the --enu‐
245 merate option.
246
247 -I, --index=TIA,II
248 where TIA,II is an type header index (TI) or Element type abbre‐
249 viation (A) followed by an individual index (II). See the IN‐
250 DEXES section below. If the --page=PG option is not given then
251 the Enclosure Status (or Control) dpage is assumed. May be used
252 with the --join option or one of the --clear=STR, --get=STR or
253 --set=STR options. To enumerate the available Element type ab‐
254 breviations use the --enumerate option.
255
256 -X, --inhex=FN
257 where FN is a filename. It has the equivalent action of the
258 --data=@FN option. If FN is '-' then stdin is read. This option
259 has been given for compatibility with other utilities in this
260 package that use --inhex=FN (or --in=FN) is a similar way. See
261 the "FORMAT OF FILES CONTAINING ASCII HEX" section in the
262 sg3_utils manpage for more information.
263
264 -i, --inner-hex
265 the outer levels of a status dpage are decoded and printed out
266 but the innermost level (e.g. the Element Status Descriptor) is
267 output in hex. Also active with the Additional Element Status
268 and Threshold In dpages. Can be used with an indexing option
269 and/or --join options.
270
271 -j, --join
272 group elements from the Element Descriptor, Enclosure Status and
273 Additional Element Status dpages. If this option is given twice
274 then elements from the Threshold In dpage are also grouped. The
275 order is dictated by the Configuration dpage.
276 There can be a bewildering amount of information in the "join"
277 output. The default is to output everything. Several additional
278 options are provided to cut down the amount displayed. If the
279 indexing options is given, only the matching elements and their
280 associated fields are output. The --filter option (see its de‐
281 scription) can be added to reduce the amount of output. Also
282 "--page=aes" (or "-p 0xa") can be added to suppress the output
283 of rows that don't have a "aes" dpage component. See the INDEXES
284 and DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS sections
285 below.
286
287 -l, --list
288 This option is equivalent to --enumerate. See that option.
289
290 -M, --mask
291 When modifying elements, the default action is a read (status
292 element), mask, modify (based on --clear=STR or --set=STR) then
293 write back as the control element. The mask step is new in
294 sg_ses version 1.98 and is based on what is allowable (and in
295 the same location) in draft SES-3 revision 6. Those masks may
296 evolve, as they have in the past. This option re-instates the
297 previous logic which was to ignore the mask step. The default
298 action (i.e. without this option) is to perform the mask step in
299 the read-mask-modify-write sequence.
300
301 -m, --maxlen=LEN
302 LEN is placed in the ALLOCATION LENGTH field of the SCSI RECEIVE
303 DIAGNOSTIC RESULTS commands sent by the utility. It represents
304 the maximum size of data the SES device can return (in bytes).
305 It cannot exceed 65535 and defaults to 65532 (bytes). Some sys‐
306 tems may not permit such large sizes hence the need for this op‐
307 tion. If LEN is less than 0 or greater than 65535 then an error
308 is generated. If LEN is 0 then the default value is used, other‐
309 wise if it is less than 4 then it is ignored (and a warning is
310 sent to stderr).
311
312 -n, --nickname=SEN
313 where SEN is the new Subenclosure Nickname. Only the first 32
314 characters (bytes) of SEN are used, if more are given they are
315 ignored. See the SETTING SUBENCLOSURE NICKNAME section below.
316
317 -N, --nickid=SEID
318 where SEID is the Subenclosure identifier that the new Nickname
319 (SEN) will be applied to. So SEID must be an existing Subenclo‐
320 sure identifier. The default value is 0 which is the main enclo‐
321 sure.
322
323 -p, --page=PG
324 where PG is a dpage abbreviation or code (a number). If PG
325 starts with a digit it is assumed to be in decimal unless pre‐
326 fixed by 0x for hex. Valid range is 0 to 255 (0x0 to 0xff) in‐
327 clusive. Default is dpage 'sdp' which is page_code 0 (i.e. "Sup‐
328 ported Diagnostic Pages") if no other options are given.
329 Page code 0xff or abbreviation "all" is not a real dpage (as the
330 highest real dpage is 0x3f) but instead causes all dpages whose
331 page code is 0x2f or less to be output. This can be used with
332 either the -HHHH or -rr to send either hexadecimal ASCII or bi‐
333 nary respectively to stdout.
334 To list the available dpage abbreviations give "xxx" for PG; the
335 same information can also be found with the --enumerate option.
336
337 -q, --quiet
338 this suppresses the number of warnings and messages output. The
339 exit status of the utility is unaffected by this option.
340
341 -r, --raw
342 outputs the chosen status dpage in ASCII hex in a format suit‐
343 able for a later invocation using the --data= option. A dpage
344 less its first 4 bytes (page code and length) is output. When
345 used twice (e.g. -rr) the full dpage contents is output in bi‐
346 nary to stdout.
347 when -rr is used together with the --data=- or --data=@FN then
348 stdin or file FN is decoded as a binary stream that continues to
349 be read until an end of file (EOF). Once that data is read then
350 the internal raw option is cleared to 0 so the output is not ef‐
351 fected. So the -rr option either changes how the input or output
352 is treated, but not both.
353
354 -R, --readonly
355 open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag).
356 The default is to open it read-write.
357
358 -A, --sas-addr=SA
359 this is an indexing method for SAS end devices (e.g. SAS disks).
360 The utility will try to find the element or slot in the Addi‐
361 tional Element Status dpage whose SAS address matches SA. For a
362 SAS disk or tape that SAS address is its target port identifier
363 for the port connected to that element or slot. Most SAS disks
364 and tapes have two such target ports, usually numbered consecu‐
365 tively.
366 SATA devices in a SAS enclosure often receive "manufactured"
367 target port identifiers from a SAS expander; typically will have
368 a SAS address close to, but different from, the SAS address of
369 the expander itself. Note that this manufactured target port
370 identifier is different from a SATA disk's WWN.
371 SA is a hex number that is up to 8 digits long. It may have a
372 leading '0x' or '0X' or a trailing 'h' or 'H'. This option is a
373 medium level
374 indexing alternative to the low level --index= options. See
375 the DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS section
376 below.
377
378 -S, --set=STR
379 Used to set an element field in the Enclosure Control or Thresh‐
380 old Out dpage. Must be used together with an indexing option to
381 specify which element is to be changed. The Enclosure Control
382 dpage is assumed if the --page=PG option is not given. See the
383 STR FORMAT and CLEAR, GET, SET sections below.
384
385 -s, --status
386 will fetch dpage from the DEVICE via a SCSI RECEIVE DIAGNOSTIC
387 RESULTS command (or from --data=@FN). In the absence of other
388 options that imply modifying a dpage (e.g. --control or
389 --set=STR) then --status is assumed, except when the --data= op‐
390 tion is given. When the --data= option is given there is no de‐
391 fault action: either the --control or this option must be given
392 to distinguish between the two different ways that data will be
393 treated.
394
395 -v, --verbose
396 increase the level of verbosity. For example when this option is
397 given four times (in which case the short form is more conve‐
398 nient: '-vvvv') then if the internal join array has been gener‐
399 ated then it is output to stderr in a form suitable for debug‐
400 ging.
401
402 -V, --version
403 print the version string and then exit.
404
405 -w, --warn
406 warn about certain irregularities with warnings sent to stderr.
407 The join is a complex operation that relies on information from
408 several dpages to be synchronized. The quality of SES devices
409 vary and to be fair, the descriptions from T10 drafts and stan‐
410 dards have been tweaked several times (see the EIIOE field) in
411 order to clear up confusion.
412
414 An enclosure can have information about its disk and tape drives plus
415 other supporting components like power supplies spread across several
416 dpages. Addressing a specific element (overall or individual) within a
417 dpage is complicated. This section describes low level indexing (i.e.
418 choosing a single element (or a group of related elements) from a large
419 number of elements). If available, the medium level indexing described
420 in the following section (DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS
421 ADDRESS) might be simpler to use.
422
423 The Configuration dpage is key to low level indexing: it contains a
424 list of "type headers", each of which contains an Element type (e.g.
425 Array Device Slot), a Subenclosure identifier (0 for the primary enclo‐
426 sure) and a "Number of possible elements". Corresponding to each type
427 header, the Enclosure Status dpage has one "overall" element plus "Num‐
428 ber of possible elements" individual elements all of which have the
429 given Element type. For some Element types the "Number of possible ele‐
430 ments" will be 0 so the Enclosure Status dpage has only one "overall"
431 element corresponding to that type header. The Element Descriptor dpage
432 and the Threshold (In and Out) dpages follow the same pattern as the
433 Enclosure Status dpage.
434
435 The numeric index corresponding to the overall element is "-1". If the
436 Configuration dpage indicates a particular element type has "n" ele‐
437 ments and n is greater than 0 then its indexes range from 0 to n-1 .
438
439 The Additional Element Status dpage is a bit more complicated. It has
440 entries for "Number of possible elements" of certain Element types. It
441 does not have entries corresponding to the "overall" elements. To make
442 the correspondence a little clearer each descriptor in this dpage op‐
443 tionally contains an "Element Index Present" (EIP) indicator. If EIP is
444 set then each element's "Element Index" field refers to the position of
445 the corresponding element in the Enclosure Status dpage.
446
447 Addressing a single overall element or a single individual element is
448 done with two indexes: TI and II. Both are origin 0. TI=0 corresponds
449 to the first type header entry which must be a Device Slot or Array De‐
450 vice Slot Element type (according to the SES-2 standard). To address
451 the corresponding overall instance, II is set to -1, otherwise II can
452 be set to the individual instance index. As an alternative to the type
453 header index (TI), an Element type abbreviation (A) optionally followed
454 by a number (e.g. "ps" refers to the first Power Supply Element type;
455 "ps1" refers to the second) can be given.
456
457 One of two command lines variants can be used to specify indexes: --in‐
458 dex=TIA,II where TIA is either an type header index (TI) or an Element
459 type abbreviation (A) (e.g. "ps" or "ps1"). II is either an individual
460 index or "-1" to specify the overall element. The second variant is
461 --index=IIA where IIA is either an individual index (II) or an Element
462 type abbreviation (A). When IIA is an individual index then the option
463 is equivalent to --index=0,II. When IIA is an Element type abbreviation
464 then the option is equivalent to --index=A,-1.
465
466 Wherever an individual index is applicable, it can be replaced by an
467 individual index range. It has the form: <first_ii>-<last_ii>. For ex‐
468 ample: '3-5' will select individual indexes 3, 4 and 5 .
469
470 To cope with vendor specific Element types (whose type codes should be
471 in the range 128 to 255) the Element type code can be given as a number
472 with a leading underscore. For example these are equivalent: --in‐
473 dex=arr and --index=_23 since the Array Device Slot Element type code
474 is 23. Also --index=ps1 and --index=_2_1 are equivalent.
475
476 Another example: if the first type header in the Configuration dpage
477 has has Array Device Slot Element type then --index=0,-1 is equivalent
478 to --index=arr. Also --index=arr,3 is equivalent to --index=3.
479
480 The --index= options can be used to reduce the amount of output (e.g.
481 only showing the element associated with the second 12 volt power sup‐
482 ply). They may also be used together with with the --clear=STR,
483 --get=STR and --set=STR options which are described in the STR section
484 below.
485
487 The three options: --descriptor=DES, --dev-slot-num=SN and
488 --sas-addr=SA allow medium level indexing, as an alternative to the low
489 level --index= options. Only one of the three options can be used in an
490 invocation. Each of the three options implicitly set the --join option
491 since they need either the Element Descriptor dpage or the Additional
492 Element Status dpage as well as the dpages needed by the --index= op‐
493 tion.
494
495 These medium level indexing options need support from the SES device
496 and that support is optional. For example the --descriptor=DES needs
497 the Element Descriptor dpage provided by the SES device however that is
498 optional. Also the provided descriptor names need to be useful, and
499 having descriptor names which are all "0" is not very useful. Also some
500 elements (e.g. overall elements) may not have descriptor names.
501
502 These medium level indexing options can be used to reduce the amount of
503 output (e.g. only showing the elements related to device slot number
504 3). They may also be used together with with the --clear=STR,
505 --get=STR and --set=STR options which are described in the following
506 section. Note that even if a field can be set (e.g. "do not remove"
507 (dnr)) and that field can be read back with --get=STR confirming that
508 change, the disk array may still ignore it (e.g. because it does not
509 have the mechanism to lock the disk drawer).
510
512 The STR operands of the --clear=STR, --get=STR and --set=STR options
513 all have the same structure. There are two forms:
514 <acronym>[=<value>]
515 <start_byte>:<start_bit>[:<num_bits>][=<value>]
516
517 The <acronym> is one of a list of common fields (e.g. "ident" and
518 "fault") that the utility converts internally into the second form. The
519 <start_byte> is usually in the range 0 to 3, the <start_bit> must be in
520 the range 0 to 7 and the <num_bits> must be in the range 1 to 64 (de‐
521 fault 1). The number of bits are read in the left to right sense of the
522 element tables shown in the various SES draft documents. For example
523 the 8 bits of byte 2 would be represented as 2:7:8 with the most sig‐
524 nificant bit being 2:7 and the least significant bit being 2:0 .
525
526 The <value> is optional but is ignored if provided to --get=STR. For
527 --set=STR the default <value> is 1 while for --clear=STR the default
528 value is 0 . <value> is assumed to be decimal, hexadecimal values can
529 be given in the normal fashion.
530
531 The supported list of <acronym>s can be viewed by using the --enumerate
532 option twice (or "-ee").
533
535 The --clear=STR, --get=STR and --set=STR options can be used up to 8
536 times in the same invocation. Any <acronym>s used in the STR operands
537 must refer to the same dpage.
538
539 When multiple of these options are used (maximum: 8), they are applied
540 in the order in which they appear on the command line. So if options
541 contradict each other, the last one appearing on the command line will
542 be enforced. When there are multiple --clear=STR and --set=STR options,
543 then the dpage they refer to is only written after the last one.
544
546 This section describes the two scenarios that can occur when the
547 --data= option is given. These scenarios are the same irrespective of
548 whether the argument to the --data= option is a string of hex bytes on
549 the command line, stdin (indicated by --data=-) or names a file (e.g.
550 --data=@thresh_in_dpage.hex).
551
552 The first scenario is flagged by the --control option. It uses the sup‐
553 plied data to build a 'control' dpage that will be sent to the DEVICE
554 using the SCSI SCSI SEND DIAGNOSTIC command. The supplied dpage data
555 should not include its first 4 bytes. Those 4 bytes are added by this
556 utility using the --page=PG option with PG placed at byte offset 0). If
557 needed, the --byte1=B1 option sets byte offset 1, else 0 is placed in
558 that position. The number of bytes decoded from the data provided (i.e.
559 its length) goes into byte offsets 2 and 3.
560
561 The second scenario is flagged by the --status option. It decodes the
562 supplied data assuming that it represents the response to one or more
563 SCSI RECEIVE DIAGNOSTIC RESULTS commands. Those responses have typi‐
564 cally been captured from some earlier invocation(s) of this utility.
565 Those earlier invocations could use the '-HHH' or '-HHHH' option and
566 file redirection to capture that response (or responses) in hexadeci‐
567 mal. The supplied dpage response data is decoded according to the other
568 command line options. For example the --join option could be given and
569 that would require the data from multiple dpages typically: Configura‐
570 tion, Enclosure status, Element descriptor and Additional element sta‐
571 tus dpages. If in doubt use --page=all in the capture phase; having
572 more dpages than needed is not a problem.
573
574 By default the user supplied data is assumed to be ASCII hexadecimal in
575 lines that don't exceed 512 characters. Anything on a line from and in‐
576 cluding a hash mark ('#') to the end of line is ignored. An end of line
577 can be a LF or CR,LF and blank lines are ignored. Each separated pair
578 (or single) hexadecimal digits represent a byte (and neither a leading
579 '0x' nor a trailing 'h' should be given). Separators are either space,
580 tab, comma or end of line.
581
582 Alternatively binary can be used and this is flagged by the '-rr' op‐
583 tion. The --data=H,H... form cannot use binary values for the 'H's,
584 only ASCII hexadecimal. The other two forms (--data=- and --data=@FN)
585 may contain binary data. Note that when the '-rr' option is used with
586 --data=@FN that it only changes the interpretation of the input data,
587 it does not change the decoding and output representation.
588
590 This utility has various techniques for changing the state of a SES de‐
591 vice. As noted above this is typically a read-modify-write type opera‐
592 tion. Most modifiable dpages have a "status" (or "in") page that can
593 be read, and a corresponding "control" (or "out") dpage that can be
594 written back to change the state of the enclosure.
595
596 The lower level technique provided by this utility involves outputting
597 a "status" dpage in hex with --raw. Then a text editor can be used to
598 edit the hex (note: to change an Enclosure Control descriptor the SE‐
599 LECT bit needs to be set). Next the control dpage data can fed back
600 with the --data=H,H... option together with the --control option; the
601 --byte1=B1 option may need to be given as well.
602
603 Changes to the Enclosure Control dpage (and the Threshold Out dpage)
604 can be done at a higher level. This involves choosing a dpage (the de‐
605 fault in this case is the Enclosure Control dpage). Next choose an in‐
606 dividual or overall element index (or name it with its Element Descrip‐
607 tor string). Then give the element's name (e.g. "ident" for RQST IDENT)
608 or its position within that element (e.g. in an Array Device Slot Con‐
609 trol element RQST IDENT is byte 2, bit 1 and 1 bit long ("2:1:1")). Fi‐
610 nally a value can be given, if not the value for --set=STR defaults to
611 1 and for --clear=STR defaults to 0.
612
614 The format of the Subenclosure Nickname control dpage is different from
615 its corresponding status dpage. The status dpage reports all Subenclo‐
616 sure Nicknames (and Subenclosure identifier 0 is the main enclosure)
617 while the control dpage allows only one of them to be changed. There‐
618 fore using the --data option technique to change a Subenclosure nick‐
619 name is difficult (but still possible).
620
621 To simplify changing a Subenclosure nickname the --nickname=SEN and
622 --nickid=SEID options have been added. If the SEN string contains spa‐
623 ces or other punctuation, it should be quoted: surrounded by single or
624 double quotes (or the offending characters escaped). If the
625 --nickid=SEID is not given then a Subenclosure identifier of 0 is as‐
626 sumed. As a guard the --control option must also be given. If the
627 --page=PG option is not given then --page=snic is assumed.
628
629 When --nickname=SEN is given then the Subenclosure Nickname Status
630 dpage is read to obtain the Generation Code field. That Generation Code
631 together with no more than 32 bytes from the Nickname (SEN) and the
632 Subenclosure Identifier (SEID) are written to the Subenclosure Nickname
633 Control dpage.
634
635 There is an example of changing a nickname in the EXAMPLES section be‐
636 low.
637
639 Support has been added to sg_ses (actually, its underlying library) for
640 NVMe (also known as NVM Express) Enclosures. It can be considered ex‐
641 perimental in sg3_utils package version 1.43 and sg_ses version 2.34 .
642
643 This support is based on a decision by NVME-MI (Management Interface)
644 developers to support the SES-3 standard. This was facilitated by
645 adding NVME-MI SES Send and SES Receive commands that tunnel dpage con‐
646 tents as used by SES.
647
649 This utility can be used to fetch arbitrary (i.e. non SES) dpages (us‐
650 ing the SCSI READ DIAGNOSTIC command). To this end the --page=PG and
651 --hex options would be appropriate. Non-SES dpages can be sent to a de‐
652 vice with the sg_senddiag utility.
653
654 The most troublesome part of the join operation is associating Addi‐
655 tional Element Status descriptors correctly. At least one SES device
656 vendor has misinterpreted the SES-2 standard, specifically with its
657 "element index" field interpretation. The code in this utility inter‐
658 prets the "element index" field as per the SES-2 standard and if that
659 yields an inappropriate Element type, adjusts its indexing to follow
660 that vendor's misinterpretation. The SES-3 drafts have introduced the
661 EIIOE (Element Index Includes Overall Elements) bit which later became
662 a 2 bit field to resolve this ambiguity. See the --eiioe=A_F option.
663
664 In draft SES-3 revision 5 the "Door Lock" element name was changed to
665 the "Door" (and an OPEN field was added to the status element). As a
666 consequence the former 'dl' element type abbreviation has been changed
667 to 'do'.
668
669 There is a related command set called SAF-TE (SCSI attached fault-tol‐
670 erant enclosure) for enclosure (including RAID) status and control.
671 SCSI devices that support SAF-TE report "Processor" peripheral device
672 type (0x3) in their INQUIRY response. See the sg_safte utility in this
673 package or the safte-monitor utility on the Internet.
674
675 The internal join array is statically allocated and its size is con‐
676 trolled by the MX_JOIN_ROWS define. Its current value is 520.
677
679 Examples can also be found at http://sg.danny.cz/sg/sg_ses.html
680
681 The following examples use Linux device names. For suitable device
682 names in other supported Operating Systems see the sg3_utils(8) man
683 page.
684
685 To view the supported dpages:
686
687 sg_ses /dev/bsg/6:0:2:0
688
689 To view the Configuration Diagnostic dpage:
690
691 sg_ses --page=cf /dev/bsg/6:0:2:0
692
693 To view the Enclosure Status dpage:
694
695 sg_ses --page=es /dev/bsg/6:0:2:0
696
697 To get the (attached) SAS address of that device (which is held in the
698 Additional Element Sense dpage (dpage 10)) printed on hex:
699
700 sg_ses -p aes -D ArrayDevice07 -G at_sas_addr -H /dev/sg3
701
702 To collate the information in the Enclosure Status, Element Descriptor
703 and Additional Element Status dpages the --join option can be used:
704
705 sg_ses --join /dev/sg3
706
707 This will produce a lot of output. To filter out lines that don't con‐
708 tain much information add the --filter option:
709
710 sg_ses --join --filter /dev/sg3
711
712 Fields in the various elements of the Enclosure Control and Threshold
713 dpages can be changed with the --clear=STR and --set=STR options. [All
714 modifiable dpages can be changed with the --raw and --data=H,H... op‐
715 tions.] The following example looks at making the "ident" LED (also
716 called "locate") flash on "ArrayDevice07" which is a disk (or more pre‐
717 cisely the carrier drawer the disk is in):
718
719 sg_ses --index=7 --set=2:1:1 /dev/sg3
720
721 If the Element Descriptor diagnostic dpage shows that "ArrayDevice07"
722 is the descriptor name associated with element index 7 then this invo‐
723 cation is equivalent to the previous one:
724
725 sg_ses --descriptor=ArrayDevice07 --set=2:1:1 /dev/sg3
726
727 Further the byte 2, bit 1 (for 1 bit) field in the Array Device Slot
728 Control element is RQST IDENT for asking a disk carrier to flash a LED
729 so it can be located. In this case "ident" (or "locate") is accepted as
730 an acronym for that field:
731
732 sg_ses --descriptor=ArrayDevice07 --set=ident /dev/sg3
733
734 To stop that LED flashing:
735
736 sg_ses --dev-slot-num=7 --clear=ident /dev/sg3
737
738 The above assumes the descriptor name 'ArrayDevice07' corresponds to
739 device slot number 7.
740
741 Now for an example of a more general but lower level technique for
742 changing a modifiable diagnostic dpage. The String (In and Out) diag‐
743 nostics dpage is relatively simple (compared with the Enclosure Sta‐
744 tus/Control dpage). However the use of this lower level technique is
745 awkward involving three steps: read, modify then write. First check the
746 current String (In) dpage contents:
747
748 sg_ses --page=str /dev/bsg/6:0:2:0
749
750 Now the "read" step. The following command will send the contents of
751 the String dpage (from byte 4 onwards) to stdout. The output will be in
752 ASCII hex with pairs of hex digits representing a byte, 16 pairs per
753 line, space separated. The redirection puts stdout in a file called
754 "t":
755
756 sg_ses --page=str --raw /dev/bsg/6:0:2:0 > t
757
758 Then with the aid of the SES-3 document (in revision 3: section 6.1.6)
759 use your favourite editor to change t. The changes can be sent to the
760 device with:
761
762 sg_ses --page=str --control --data=- /dev/bsg/6:0:2:0 < t
763
764 If the above is successful, the String dpage should have been changed.
765 To check try:
766
767 sg_ses --page=str /dev/bsg/6:0:2:0
768
769 To change the nickname on the main enclosure:
770
771 sg_ses --nickname='1st enclosure' --control /dev/bsg/6:0:2:0
772
773 To capture the whole state of an enclosure (from a SES perspective) for
774 later analysis, this can be done:
775
776 sg_ses --page=all -HHHH /dev/sg5 > enc_sg5_all.hex
777
778 Note that if there are errors or warnings they will be sent to stderr
779 so they will appear on the command line (since only stdout is redi‐
780 rected). A text editor could be used to inspect enc_sg5_all.hex . If
781 all looks in order at some later time, potentially on a different ma‐
782 chine where enc_sg5_all.hex has been copied, a "join" could be done.
783 Note that join reflects the state of the enclosure when the capture was
784 done.
785
786 sg_ses --data=@enc_sg5_all.hex --status --join
787
789 The exit status of sg_ses is 0 when it is successful. Otherwise see the
790 sg3_utils(8) man page.
791
793 Written by Douglas Gilbert.
794
796 Report bugs to <dgilbert at interlog dot com>.
797
799 Copyright © 2004-2021 Douglas Gilbert
800 This software is distributed under a FreeBSD license. There is NO war‐
801 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
802 POSE.
803
805 sg_inq, sg_safte, sg_senddiag, sg_ses_microcode, sg3_utils (sg3_utils);
806 safte-monitor (Internet)
807
808
809
810sg3_utils-1.46 February 2021 SG_SES(8)