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