aboutsummaryrefslogtreecommitdiff
path: root/doc/sg_ses.8
blob: 8042b05901bc03c92e79a7d8729be43e33d290fc (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
.TH SG_SES "8" "December 2017" "sg3_utils\-1.43" SG3_UTILS
.SH NAME
sg_ses \- access a SCSI Enclosure Services (SES) device
.SH SYNOPSIS
.B sg_ses
[\fI\-\-descriptor=DN\fR] [\fI\-\-dev\-slot\-num=SN\fR] [\fI\-\-eiioe=A_F\fR]
[\fI\-\-filter\fR] [\fI\-\-get=STR\fR] [\fI\-\-hex\fR]
[\fI\-\-index=IIA\fR | \fI\-\-index=TIA,II\fR] [\fI\-\-inner\-hex\fR]
[\fI\-\-join\fR] [\fI\-\-maxlen=LEN\fR] [\fI\-\-page=PG\fR] [\fI\-\-raw\fR]
[\fI\-\-readonly\fR] [\fI\-\-sas\-addr=SA\fR] [\fI\-\-status\fR]
[\fI\-\-verbose\fR] [\fI\-\-warn\fR] \fIDEVICE\fR
.PP
.B sg_ses
[\fI\-\-byte1=B1\fR] [\fI\-\-clear=STR\fR] [\fI\-\-control\fR]
[\fI\-\-data=H,H...\fR] [\fI\-\-descriptor=DN\fR]
[\fI\-\-dev\-slot\-num=SN\fR] [\fI\-\-index=IIA\fR | \fI\-\-index=TIA,II\fR]
[\fI\-\-mask\fR] [\fI\-\-maxlen=LEN\fR] [\fI\-\-nickname=SEN\fR]
[\fI\-\-nickid=SEID\fR]  [\fI\-\-page=PG\fR] [\fI\-\-readonly\fR]
[\fI\-\-sas\-addr=SA\fR] [\fI\-\-set=STR\fR] [\fI\-\-verbose\fR]
\fIDEVICE\fR
.PP
.B sg_ses
[\fI\-\-enumerate\fR] [\fI\-\-index=IIA\fR] [\fI\-\-list\fR] [\fI\-\-help\fR]
[\fI\-\-version\fR]
.SH DESCRIPTION
.\" Add any additional description here
.PP
Fetches management information from a SCSI Enclosure Service (SES) device.
This utility can also modify the state of a SES device. The \fIDEVICE\fR
should be a SES device which may be a dedicated enclosure services
processor in which case an INQUIRY response's Peripheral Device Type is
13 [0xd]. Alternatively it may be attached to another type of SCSI
device (e.g. a disk) in which case the EncServ bit is set in its INQUIRY
response.
.PP
If the \fIDEVICE\fR argument is given with no options then the names of all
diagnostic pages supported are listed. Most, but not necessarily all, of the
named diagnostic pages are defined in the SES standards and drafts. The most
recent reference for this utility is the draft SCSI Enclosure Services 4
document T10/BSR INCITS 555 Revision 1 at http://www.t10.org . Existing
standards for SES, SES\-2 and SES\-3 are ANSI INCITS 305\-1998 and ANSI
INCITS 448\-2008 and ANSI INCITS 518\-2017 respectively.
.PP
The first form shown in the synopsis is for fetching and decoding pages
or fields from the SES \fIDEVICE\fR. Alternatively a fetched page may be
output in hex or binary with the \fI\-\-hex\fR or \fI\-\-raw\fR options.
.PP
The second form in the synopsis is for modifying pages or fields held in
the SES \fIDEVICE\fR. Changing the state of an enclosure (e.g. requesting
the "ident" (locate) LED to flash on a disk carrier in an array) is typically
done using a read\-modify\-write cycle. See the section on CHANGING STATE
below.
.PP
The third form in the synopsis shows the options for providing command line
help (i.e. usage information), listing out page and field information tables
held by the utility (\fI\-\-enumerate\fR), or printing the version string
of this utility.
.PP
There is a web page discussing this utility at
http://sg.danny.cz/sg/sg_ses.html . Support for downloading microcode to
a SES device has been placed in a separate utility called sg_ses_microcode.
.PP
In the following sections "page" refers to a diagnostic page, either
fetched with a SCSI RECEIVE DIAGNOSTIC RESULTS command or sent to the
\fIDEVICE\fR with a SCSI SEND DIAGNOSTIC command.
.SH OPTIONS
Arguments to long options are mandatory for short options as well.
The options are arranged in alphabetical order based on the long
option name.
.TP
\fB\-b\fR, \fB\-\-byte1\fR=\fIB1\fR
some modifiable pages may need byte 1 (i.e. the second byte) set. In the
Enclosure Control page, byte 1 contains the INFO, NON\-CRIT, CRIT and
UNRECOV bits. In the Subenclosure String Out, Subenclosure Nickname Control
and Download Microcode Control pages, byte 1 is the Subenclosure identifier.
Active when the \fI\-\-control\fR and \fI\-\-data=H,H...\fR options are used
and the default value is 0. If the \fI\-\-clear=STR\fR or \fI\-\-set=STR\fR
option is used then the value read from byte 1 is written back to byte 1.
\fIB1\fR is in decimal unless it is prefixed by '0x' or '0X' (or has a
trailing 'h' or 'H').
.TP
\fB\-C\fR, \fB\-\-clear\fR=\fISTR\fR
Used to clear an element field in the Enclosure Control or Threshold Out
page. Must be used together with an indexing option to specify which element
is to be changed. The Enclosure Control page is assumed if the
\fI\-\-page=PG\fR option is not given. See the STR FORMAT and the CLEAR, GET,
SET sections below.
.TP
\fB\-c\fR, \fB\-\-control\fR
will send control information to the \fIDEVICE\fR via a SCSI SEND
DIAGNOSTIC command. Cannot give both this option and \fI\-\-status\fR.
The Enclosure Control, String Out, Threshold Out, Array Control (obsolete
in SES\-2), Subenclosure String Out, Subenclosure Nickname Control and
Download Microcode pages can be set currently. This option is assumed if
either the \fI\-\-clear=STR\fR or \fI\-\-set=STR\fR option is given.
.TP
\fB\-d\fR, \fB\-\-data\fR=\fIH,H...\fR
permits a string of comma separated (ASCII) hex bytes to be specified (limit
1024). A (single) space separated string of hex bytes is also allowed but
the list needs to be in quotes. This option allows the parameters to a
control page to be specified. The string given should not include the first 4
bytes (i.e. page code and length).
.TP
\fB\-d\fR, \fB\-\-data\fR=\-
reads one or more data strings from stdin, limit 2048 bytes. stdin may
provide ASCII hex as a comma separated list (i.e. as with the
\fI\-\-data=H,H...\fR option). Additionally spaces, tabs and line feeds are
permitted as separators from stdin . Stops reading stdin when an EOF is
detected.
.TP
\fB\-d\fR, \fB\-\-data\fR=@\fIFN\fR
reads one or more data strings from the file called \fIFN\fR, limit 2048
bytes. The contents of the file is decoded in the same fashion as stdin
described in the previous option.
.TP
\fB\-D\fR, \fB\-\-descriptor\fR=\fIDN\fR
where \fIDN\fR is a descriptor name (string) as found in the Element
Descriptor page. This is a medium level indexing alternative to the low
level \fI\-\-index=\fR options. If the descriptor name contains a space then
\fIDN\fR needs to be surrounded by quotes (single or double) or the space
escaped (e.g. preceded by a backslash). See the DESCRIPTOR NAME, DEVICE SLOT
NUMBER AND SAS ADDRESS section below.
.TP
\fB\-x\fR, \fB\-\-dev\-slot\-num\fR=\fISN\fR, \fB\-\-dsn\fR=\fISN\fR
where \fISN\fR is a device slot number found in the Additional Element Status
page. Only entries for FCP and SAS devices (with EIP=1) have device slot
numbers. \fISN\fR must be a number in the range 0 to 255 (inclusive). 255 is
used to indicate there is no corresponding device slot. This is a medium level
indexing alternative to the low level \fI\-\-index=\fR options. See the
DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS section below.
.TP
\fB\-E\fR, \fB\-\-eiioe\fR=\fIA_F\fR
\fIA_F\fR is either the string 'auto' or 'force'. There was some fuzziness
in the interpretation of the 'element index' field in the Additional Element
Status (AES) page between SES\-2 and SES\-3. The EIIOE bit was introduced to
resolve the problem but not all enclosures have caught up. In the SES\-3
revision 12 draft the EIIOE bit was expanded to a 2 bit EIIOE field.
Using '\-\-eiioe=force' will decode the AES page as if the EIIOE field is set
to 1.  Using '\-\-eiioe=auto' will decode the AES page as if the EIIOE field
is set to 1 if the first AES descriptor has its EIP bit set and its element
index field is 1 (in other words a heuristic to guess whether the EIIOE field
should be set to 1 or 0).
.br
If the enclosure sets the actual EIIOE field to 1 or more then this option has
no effect. It is recommended that HP JBOD users set \-\-eiioe=auto .
.TP
\fB\-e\fR, \fB\-\-enumerate\fR
enumerate all known page names and SES elements when this option is given
once.
.br
If \fI\-\-enumerate\fR is given twice, then the recognised acronyms for the
\fI\-\-clear=STR\fR, \fI\-\-get=STR\fR and \fI\-\-set=STR\fR options are
listed. The utility exits after listing this information (so most other
options and \fIDEVICE\fR are ignored). Since there are many acronyms for
the Enclosure Control/Status page then the output can be further restricted
by giving the \fI\-\-index=IIA\fR option (e.g. "sg_ses \-ee \-I ts" to only
show the acronyms associated with the Enclosure Control/Status page's
Temperature Sensor Element Type).
.TP
\fB\-f\fR, \fB\-\-filter\fR
cuts down on the amount of output from the Enclosure Status page and the
Additional Element Status page. When this option is given, any line which
has all its binary flags cleared (i.e. 0) is filtered out (i.e.  ignored).
If a line has some other value on it (e.g. a temperature) then it is output.
When this option is used twice only elements associated with the "status=ok"
field (in the Enclosure status page) are output. The \fI\-\-filter\fR option
is useful for reducing the amount of output generated by the \fI\-\-join\fR
option.
.TP
\fB\-G\fR, \fB\-\-get\fR=\fISTR\fR
Used to read a field in a status element. Must be used together with a an
indexing option to specify which element is to be read. By default the
Enclosure Status page is read, the only other pages that can be read are the
Threshold In and Additional Element Status pages. If a value is found it is
output in decimal to stdout (by default) or in hexadecimal preceded by "0x"
if the \fI\-\-hex\fR option is also given. See the STR FORMAT and the CLEAR,
GET, SET sections below.
.TP
\fB\-h\fR, \fB\-\-help\fR
output the usage message then exit. Since there is a lot of information,
it is split into two pages. The most important is shown on the first page.
Use this option twice (e.g. '\-hh') to output the second page. Note: the
\fI\-\-enumerate\fR option might also be viewed as a help or usage type
option. And like this option it has a "given twice" form: '\-ee'.
.TP
\fB\-H\fR, \fB\-\-hex\fR
If the \fI\-\-get=STR\fR option is given then output the value found (if
any) in hexadecimal, with a leading "0x". Otherwise output the response
in hexadecimal; with trailing ASCII if given once, without it if given
twice, and simple hex if given three or more times. Ignored when all
elements from several pages are being accessed (e.g. when the \fI\-\-join\fR
option is used). Also see the \fI\-\-raw\fR option which may be used
with this option.
.TP
\fB\-I\fR, \fB\-\-index\fR=\fIIIA\fR
where \fIIIA\fR is either an individual index (II) or an Element type
abbreviation (A). See the INDEXES section below. If the \fI\-\-page=PG\fR
option is not given then the Enclosure Status (or Control) page is assumed.
May be used with the \fI\-\-join\fR option or one of the \fI\-\-clear=STR\fR,
\fI\-\-get=STR\fR or \fI\-\-set=STR\fR options. To enumerate the available
Element type abbreviations use the \fI\-\-enumerate\fR option.
.TP
\fB\-I\fR, \fB\-\-index\fR=\fITIA,II\fR
where \fITIA,II\fR is an type header index (TI) or Element type
abbreviation (A) followed by an individual index (II). See the INDEXES section
below. If the \fI\-\-page=PG\fR option is not given then the Enclosure
Status (or Control) page is assumed. May be used with the \fI\-\-join\fR
option or one of the \fI\-\-clear=STR\fR, \fI\-\-get=STR\fR or
\fI\-\-set=STR\fR options. To enumerate the available Element type
abbreviations use the \fI\-\-enumerate\fR option.
.TP
\fB\-i\fR, \fB\-\-inner\-hex\fR
the outer levels of a status page are decoded and printed out but the
innermost level (e.g. the Element Status Descriptor) is output in hex. Also
active with the Additional Element Status and Threshold In pages. Can be
used with an indexing option and/or \fI\-\-join\fR options.
.TP
\fB\-j\fR, \fB\-\-join\fR
group elements from the Element Descriptor, Enclosure Status and Additional
Element Status pages. If this option is given twice then elements from the
Threshold In page are also grouped. The order is dictated by the Configuration
page.
.PP
There can be a bewildering amount of information in the "join" output. The
default is to output everything. Several additional options are provided to
cut down the amount displayed. If the indexing options is given, only the
matching elements and their associated fields are output. The \fI\-\-filter\fR
option (see its description) can be added to reduce the amount of output.
Also "\-\-page=aes" (or "\-p 0xa") can be added to suppress the output of
rows that don't have a "aes" page component. See the INDEXES and DESCRIPTOR
NAME, DEVICE SLOT NUMBER AND SAS ADDRESS sections below.
.TP
\fB\-l\fR, \fB\-\-list\fR
This option is equivalent to \fI\-\-enumerate\fR. See that option.
.TP
\fB\-M\fR, \fB\-\-mask\fR
When modifying elements, the default action is a read (status element),
mask, modify (based on \fI\-\-clear=STR\fR or \fI\-\-set=STR\fR) then write
back as the control element. The mask step is new in sg_ses version 1.98
and is based on what is allowable (and in the same location) in draft SES\-3
revision 6. Those masks may evolve, as they have in the past. This option
re\-instates the previous logic which was to ignore the mask step. The
default action (i.e. without this option) is to perform the mask step in
the read\-mask\-modify\-write sequence.
.TP
\fB\-m\fR, \fB\-\-maxlen\fR=\fILEN\fR
\fILEN\fR is placed in the ALLOCATION LENGTH field of the SCSI RECEIVE
DIAGNOSTIC RESULTS commands sent by the utility. It represents the maximum
size of data the SES device can return (in bytes). It cannot exceed 65535
and defaults to 65532 (bytes). Some systems may not permit such large sizes
hence the need for this option. If \fILEN\fR is set to 0 then the default
size is used.
.TP
\fB\-n\fR, \fB\-\-nickname\fR=\fISEN\fR
where \fISEN\fR is the new Subenclosure Nickname. Only the first 32
characters (bytes) of \fISEN\fR are used, if more are given they are
ignored. See the SETTING SUBENCLOSURE NICKNAME section below.
.TP
\fB\-N\fR, \fB\-\-nickid\fR=\fISEID\fR
where \fISEID\fR is the Subenclosure identifier that the new
Nickname (\fISEN\fR) will be applied to. So \fISEID\fR must be an existing
Subenclosure identifier. The default value is 0 which is the
main enclosure.
.TP
\fB\-p\fR, \fB\-\-page\fR=\fIPG\fR
where \fIPG\fR is a page abbreviation or code (a number). If \fIPG\fR
starts with a digit it is assumed to be in decimal unless prefixed by
0x for hex. Valid range is 0 to 255 (0x0 to 0xff) inclusive. Default is
page 'sdp' which is page_code 0 (i.e. "Supported Diagnostic Pages") if
no other options are given.
.br
To list the available page abbreviations give "xxx" for \fIPG\fR; the same
information can also be found with the \fI\-\-enumerate\fR option.
.TP
\fB\-r\fR, \fB\-\-raw\fR
outputs the chosen status page in ASCII hex in a format suitable for a
later invocation using the \fI\-\-data=\fR option. A page less its first
4 bytes (page code and length) is output. When used twice (e.g. \fI\-rr\fR)
the full page contents is output in binary to stdout.
.TP
\fB\-R\fR, \fB\-\-readonly\fR
open the \fIDEVICE\fR read\-only (e.g. in Unix with the O_RDONLY flag).
The default is to open it read\-write.
.TP
\fB\-A\fR, \fB\-\-sas\-addr\fR=\fISA\fR
this is an indexing method for SAS end devices (e.g. SAS disks). The utility
will try to find the element or slot in the Additional Element Status page
whose SAS address matches \fISA\fR. For a SAS disk or tape that SAS address
is its target port identifier for the port connected to that element or slot.
Most SAS disks and tapes have two such target ports, usually numbered
consecutively.
.br
SATA devices in a SAS enclosure often receive "manufactured" target port
identifiers from a SAS expander; typically will have a SAS address close to,
but different from, the SAS address of the expander itself. Note that this
manufactured target port identifier is different from a SATA disk's WWN.
.br
\fISA\fR is a hex number that is up to 8 digits long. It may have a
leading '0x' or '0X' or a trailing 'h' or 'H'. This option is a medium level
 indexing alternative to the low level \fI\-\-index=\fR options.
See the DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS section below.
.TP
\fB\-S\fR, \fB\-\-set\fR=\fISTR\fR
Used to set an element field in the Enclosure Control or Threshold Out page.
Must be used together with an indexing option to specify which element is to
be changed. The Enclosure Control page is assumed if the \fI\-\-page=PG\fR
option is not given. See the STR FORMAT and CLEAR, GET, SET sections below.
.TP
\fB\-s\fR, \fB\-\-status\fR
will fetch page from the \fIDEVICE\fR via a SCSI RECEIVE DIAGNOSTIC RESULTS
command. In the absence of other options that imply modifying a page (e.g.
\fI\-\-control\fR or \fI\-\-set=STR\fR) then \fI\-\-status\fR is assumed.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
increase the level of verbosity. For example when this option is given four
times (in which case the short form is more convenient: '\-vvvv') then if
the internal join array has been generated then it is output to stderr in
a form suitable for debugging.
.TP
\fB\-V\fR, \fB\-\-version\fR
print the version string and then exit.
.TP
\fB\-w\fR, \fB\-\-warn\fR
warn about certain irregularities with warnings sent to stderr. The join
is a complex operation that relies on information from several pages to be
synchronized. The quality of SES devices vary and to be fair, the
descriptions from T10 drafts and standards have been tweaked several
times (see the EIIOE field) in order to clear up confusion.
.SH INDEXES
An enclosure can have information about its disk and tape drives plus other
supporting components like power supplies spread across several pages.
Addressing a specific element (overall or individual) within a page is
complicated. This section describes low level indexing (i.e. choosing a
single element (or a group of related elements) from a large number of
elements). If available, the medium level indexing described in the
following section (DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS)
might be simpler to use.
.PP
The Configuration page is key to low level indexing: it contains a list
of "type headers", each of which contains an Element type (e.g. Array
Device Slot), a Subenclosure identifier (0 for the primary enclosure) and
a "Number of possible elements". Corresponding to each type header, the
Enclosure Status page has one "overall" element plus "Number of possible
elements" individual elements all of which have the given Element type. For
some Element types the "Number of possible elements" will be 0 so the
Enclosure Status page has only one "overall" element corresponding to that
type header. The Element Descriptor page and the Threshold (In and Out)
pages follow the same pattern as the Enclosure Status page.
.PP
The numeric index corresponding to the overall element is "\-1". If the
Configuration page indicates a particular element type has "n" elements
and n is greater than 0 then its indexes range from 0 to n-\1 . 
.PP
The Additional Element Status page is a bit more complicated. It has
entries for "Number of possible elements" of certain Element types. It
does not have entries corresponding to the "overall" elements. To make
the correspondence a little clearer each descriptor in this page optionally
contains an "Element Index Present" (EIP) indicator. If EIP is set then each
element's "Element Index" field refers to the position of the corresponding
element in the Enclosure Status page.
.PP
Addressing a single overall element or a single individual element is done
with two indexes: TI and II. Both are origin 0. TI=0 corresponds to the
first type header entry which must be a Device Slot or Array Device Slot
Element type (according to the SES\-2 standard). To address the corresponding
overall instance, II is set to \-1, otherwise II can be set to the individual
instance index. As an alternative to the type header index (TI), an Element
type abbreviation (A) optionally followed by a number (e.g. "ps" refers to
the first Power Supply Element type; "ps1" refers to the second) can be
given.
.PP
One of two command lines variants can be used to specify indexes:
\fI\-\-index=TIA,II\fR where \fITIA\fR is either an type header index (TI)
or an Element type abbreviation (A) (e.g. "ps" or "ps1"). \fIII\fR is either
an individual index or "\-1" to specify the overall element. The second
variant is \fI\-\-index=IIA\fR where \fIIIA\fR is either an individual
index (II) or an Element type abbreviation (A). When \fIIIA\fR is an
individual index then the option is equivalent to \fI\-\-index=0,II\fR. When
\fIIIA\fR is an Element type abbreviation then the option is equivalent to
\fI\-\-index=A,\-1\fR.
.PP
Wherever an individual index is applicable, it can be replaced by an
individual index range. It has the form: <first_ii>-<last_ii>. For
example: '3\-5' will select individial indexes 3, 4 and 5 .
.PP
To cope with vendor specific Element types (which should be in the range 128
to 255) the Element type can be given as a number with a leading underscore.
For example these are equivalent: \fI\-\-index=arr\fR and
\fI\-\-index=_23\fR since the Array Device Slot Element type value is 23.
Also \fI\-\-index=ps1\fR and \fI\-\-index=_2_1\fR are equivalent.
.PP
Another example: if the first type header in the Configuration page has
has Array Device Slot Element type then \fI\-\-index=0,\-1\fR is
equivalent to \fI\-\-index=arr\fR. Also \fI\-\-index=arr,3\fR is equivalent
to \fI\-\-index=3\fR.
.PP
The \fI\-\-index=\fR options  can be used to reduce the amount of
output (e.g. only showing the element associated with the second 12 volt
power supply). They may also be used together with with the
\fI\-\-clear=STR\fR, \fI\-\-get=STR\fR and \fI\-\-set=STR\fR options which
are described in the STR section below.
.SH DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS
The three options: \fI\-\-descriptor=DN\fR, \fI\-\-dev\-slot\-num=SN\fR
and \fI\-\-sas\-addr=SA\fR allow medium level indexing, as an alternative
to the low level \fI\-\-index=\fR options. Only one of the three options
can be used in an invocation. Each of the three options implicitly set the
\fI\-\-join\fR option since they need either the Element Descriptor page or
the Additional Element Status page as well as the pages needed by the
\fI\-\-index=\fR option.
.PP
These medium level indexing options need support from the SES device and
that support is optional. For example the \fI\-\-descriptor=DN\fR needs
the Element Descriptor page provided by the SES device however that is
optional. Also the provided descriptor names need to be useful, and having
descriptor names which are all "0" is not very useful. Also some
elements (e.g. overall elements) may not have descriptor names.
.PP
These medium level indexing options can be used to reduce the amount of
output (e.g. only showing the elements related to device slot number 3).
They may also be used together with with the \fI\-\-clear=STR\fR,
\fI\-\-get=STR\fR and \fI\-\-set=STR\fR options which are described in the
following section. Note that even if a field can be set (e.g. "do not
remove" (dnr)) and that field can be read back with \fI\-\-get=STR\fR
confirming that change, the disk array may still ignore it (e.g. because it
does not have the mechanism to lock the disk drawer).
.SH STR FORMAT
The \fISTR\fR operands of the \fI\-\-clear=STR\fR, \fI\-\-get=STR\fR and
\fI\-\-set=STR\fR options all have the same structure. There are two forms:
.br
      <acronym>[=<value>]
.br
      <start_byte>:<start_bit>[:<num_bits>][=<value>]
.PP
The <acronym> is one of a list of common fields (e.g. "ident" and "fault")
that the utility converts internally into the second form. The <start_byte>
is usually in the range 0 to 3, the <start_bit> must be in the range 0 to
7 and the <num_bits> must be in the range 1 to 64 (default 1). The
number of bits are read in the left to right sense of the element tables
shown in the various SES draft documents. For example the 8 bits of
byte 2 would be represented as 2:7:8 with the most significant bit being
2:7 and the least significant bit being 2:0 .
.PP
The <value> is optional but is ignored if provided to \fI\-\-get=STR\fR.
For \fI\-\-set=STR\fR the default <value> is 1 while for \fI\-\-clear=STR\fR
the default value is 0 . <value> is assumed to be decimal, hexadecimal
values can be given in the normal fashion.
.PP
The supported list of <acronym>s can be viewed by using the
\fI\-\-enumerate\fR option twice (or "\-ee").
.SH CLEAR, GET, SET
The \fI\-\-clear=STR\fR, \fI\-\-get=STR\fR and \fI\-\-set=STR\fR options can
be used up to 8 times in the same invocation. Any <acronym>s used in the
\fISTR\fR operands must refer to the same diagnostic page.
.PP
When multiple of these options are used, they are applied in the order in
which they appear on the command line. So if options contradict each other,
the last one appearing on the command line will be enforced. When there
are multiple \fI\-\-clear=STR\fR and \fI\-\-set=STR\fR options, then the
diagnostic page they refer to is only written after the last one.
.SH CHANGING STATE
This utility has various techniques for changing the state of a SES device.
As noted above this is typically a read\-modify\-write type operation.
Most modifiable pages have a "status" (or "in") page that can be read, and
a corresponding "control" (or "out") page that can be written back to change
the state of the enclosure.
.PP
The lower level technique provided by this utility involves outputting
a "status" page in hex with \fI\-\-raw\fR. Then a text editor can be used
to edit the hex (note: to change an Enclosure Control descriptor the SELECT
bit needs to be set). Next the control page data can fed back with the
\fI\-\-data=H,H...\fR option together with the \fI\-\-control\fR option;
the \fI\-\-byte1=B1\fR option may need to be given as well.
.PP
Changes to the Enclosure Control page (and the Threshold Out page) can be
done at a higher level. This involves choosing a page (the default in this
case is the Enclosure Control page). Next choose an individual or overall
element index (or name it with its Element Descriptor string). Then give
the element's name (e.g. "ident" for RQST IDENT) or its position within that
element (e.g. in an Array Device Slot Control element RQST IDENT is byte 2,
bit 1 and 1 bit long ("2:1:1")). Finally a value can be given, if not the
value for \fI\-\-set=STR\fR defaults to 1 and for \fI\-\-clear=STR\fR
defaults to 0.
.SH SETTING SUBENCLOSURE NICKNAME
The format of the Subenclosure Nickname control page is different from its
corresponding status page. The status page reports all Subenclosure
Nicknames (and Subenclosure identifier 0 is the main enclosure) while the
control page allows only one of them to be changed. Therefore using the
\fB\-\-data\fR option technique to change a Subenclosure nickname is
difficult (but still possible).
.PP
To simplify changing a Subenclosure nickname the \fI\-\-nickname=SEN\fR and
\fI\-\-nickid=SEID\fR options have been added. If the \fISEN\fR string
contains spaces or other punctuation, it should be quoted: surrounded by
single or double quotes (or the offending characters escaped). If the
\fI\-\-nickid=SEID\fR is not given then a Subenclosure identifier of 0 is
assumed. As a guard the \fI\-\-control\fR option must also be given. If
the \fI\-\-page=PG\fR option is not given then \fI\-\-page=snic\fR is
assumed.
.PP
When \fI\-\-nickname=SEN\fR is given then the Subenclosure Nickname Status
page is read to obtain the Generation Code field. That Generation Code
together with no more than 32 bytes from the Nickname (\fISEN\fR) and the
Subenclosure Identifier (\fISEID\fR) are written to the Subenclosure Nickname
Control page.
.PP
There is an example of changing a nickname in the EXAMPLES section below.
.SH NOTES
This utility can be used to fetch arbitrary (i.e. non SES) diagnostic
pages (using the SCSI READ DIAGNOSTIC command). To this end the
\fI\-\-page=PG\fR and \fI\-\-hex\fR options would be appropriate. Arbitrary
diagnostic pages can be sent to a device with the sg_senddiag utility.
.PP
The most troublesome part of the join operation is associating Additional
Element Status descriptors correctly. At least one SES device vendor has
misinterpreted the SES\-2 standard with its "element index" field. The
code in this utility interprets the "element index" field as per the SES\-2
standard and if that yields an inappropriate Element type, adjusts its
indexing to follow that vendor's misinterpretation. The SES\-3 drafts have
introduced the EIIOE (element index includes overall elements) bit which
later became a 2 bit field to resolve this ambiguity. See the
\fI\-\-eiioe=A_F\fR option.
.PP
In draft SES\-3 revision 5 the "Door Lock" element name was changed to
the "Door" (and an OPEN field was added to the status element). As a
consequence the former 'dl' element type abbreviation has been changed
to 'do'.
.PP
There is a related command set called SAF\-TE (SCSI attached fault\-tolerant
enclosure) for enclosure (including RAID) status and control. SCSI devices
that support SAF\-TE report "Processor" peripheral device type (0x3) in their
INQUIRY response. See the sg_safte utility in this package or the
safte\-monitor utility on the Internet.
.SH EXAMPLES
Examples can also be found at http://sg.danny.cz/sg/sg_ses.html
.PP
The following examples use Linux device names. For suitable device names
in other supported Operating Systems see the sg3_utils(8) man page.
.PP
To view the supported pages:
.PP
   sg_ses /dev/bsg/6:0:2:0
.PP
To view the Configuration Diagnostic page:
.PP
   sg_ses \-\-page=cf /dev/bsg/6:0:2:0
.PP
To view the Enclosure Status page:
.PP
   sg_ses \-\-page=es /dev/bsg/6:0:2:0
.PP
To get the (attached) SAS address of that device (which is held in the
Additional Element Sense page (page 10)) printed on hex:
.PP
   sg_ses \-p aes \-D ArrayDevice07 \-G at_sas_addr \-H /dev/sg3
.PP
To collate the information in the Enclosure Status, Element Descriptor
and Additional Element Status pages the \fI\-\-join\fR option can be used:
.PP
   sg_ses \-\-join /dev/sg3
.PP
This will produce a lot of output. To filter out lines that don't contain
much information add the \fI\-\-filter\fR option:
.PP
   sg_ses \-\-join \-\-filter /dev/sg3
.PP
Fields in the various elements of the Enclosure Control and Threshold pages
can be changed with the \fI\-\-clear=STR\fR and \fI\-\-set=STR\fR
options. [All modifiable pages can be changed with the \fI\-\-raw\fR and
\fI\-\-data=H,H...\fR options.] The following example looks at making
the "ident" LED (also called "locate") flash on "ArrayDevice07" which is a
disk (or more precisely the carrier drawer the disk is in):
.PP
   sg_ses \-\-index=7 \-\-set=2:1:1 /dev/sg3
.PP
If the Element Descriptor diagnostic page shows that "ArrayDevice07" is
the descriptor name associated with element index 7 then this invocation
is equivalent to the previous one:
.PP
   sg_ses \-\-descriptor=ArrayDevice07 \-\-set=2:1:1 /dev/sg3
.PP
Further the byte 2, bit 1 (for 1 bit) field in the Array Device Slot Control
element is RQST IDENT for asking a disk carrier to flash a LED so it can
be located. In this case "ident" (or "locate") is accepted as an acronym
for that field:
.PP
   sg_ses \-\-descriptor=ArrayDevice07 \-\-set=ident /dev/sg3
.PP
To stop that LED flashing:
.PP
   sg_ses \-\-dev\-slot\-num=7 \-\-clear=ident /dev/sg3
.PP
The above assumes the descriptor name 'ArrayDevice07' corresponds to device
slot number 7.
.PP
Now for an example of a more general but lower level technique for changing
a modifiable diagnostic page. The String (In and Out) diagnostics page is
relatively simple (compared with the Enclosure Status/Control page). However
the use of this lower level technique is awkward involving three steps: read,
modify then write. First check the current String (In) page contents:
.PP
   sg_ses \-\-page=str /dev/bsg/6:0:2:0
.PP
Now the "read" step. The following command will send the contents of the
String page (from byte 4 onwards) to stdout. The output will be in ASCII
hex with pairs of hex digits representing a byte, 16 pairs per line,
space separated. The redirection puts stdout in a file called "t":
.PP
   sg_ses \-\-page=str \-\-raw /dev/bsg/6:0:2:0 > t
.PP
Then with the aid of the SES\-3 document (in revision 3: section 6.1.6)
use your favourite editor to change t. The changes can be sent to the
device with:
.PP
   sg_ses \-\-page=str \-\-control \-\-data=\- /dev/bsg/6:0:2:0 < t
.PP
If the above is successful, the String page should have been changed. To
check try:
.PP
   sg_ses \-\-page=str /dev/bsg/6:0:2:0
.PP
To change the nickname on the main enclosure:
.PP
   sg_ses \-\-nickname='1st enclosure' \-\-control /dev/bsg/6:0:2:0
.SH EXIT STATUS
The exit status of sg_ses is 0 when it is successful. Otherwise see
the sg3_utils(8) man page.
.SH AUTHORS
Written by Douglas Gilbert.
.SH "REPORTING BUGS"
Report bugs to <dgilbert at interlog dot com>.
.SH COPYRIGHT
Copyright \(co 2004\-2017 Douglas Gilbert
.br
This software is distributed under a FreeBSD license. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
.B sg_inq, sg_safte, sg_senddiag, sg_ses_microcode, sg3_utils (sg3_utils);
.B safte\-monitor (Internet)