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