1SG_SES(8)                          SG3_UTILS                         SG_SES(8)
2
3
4

NAME

6       sg_ses - access a SCSI Enclosure Services (SES) device
7

SYNOPSIS

9       sg_ses  [--descriptor=DN]  [--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]     [--raw]    [--readonly]
12       [--sas-addr=SA] [--status] [--verbose] [--warn] DEVICE
13
14       sg_ses   [--byte1=B1]   [--clear=STR]    [--control]    [--data=H,H...]
15       [--descriptor=DN]  [--dev-slot-num=SN]  [--index=IIA  | --index=TIA,II]
16       [--mask] [--maxlen=LEN] [--nickname=SEN]  [--nickid=SEID]   [--page=PG]
17       [--readonly] [--sas-addr=SA] [--set=STR] [--verbose] DEVICE
18
19       sg_ses [--enumerate] [--list] [--help] [--version]
20

DESCRIPTION

22       Fetches  management  information  from  a  SCSI Enclosure Service (SES)
23       device.  This utility can also modify the state of a  SES  device.  The
24       DEVICE  should  be a SES device which may be a dedicated enclosure ser‐
25       vices processor in which case an INQUIRY response's  Peripheral  Device
26       Type  is  13 [0xd]. Alternatively it may be attached to another type of
27       SCSI device (e.g. a disk) in which case the EncServ bit is set  in  its
28       INQUIRY response.
29
30       If  the  DEVICE argument is given with no options then the names of all
31       diagnostic pages supported are listed. Most, but not  necessarily  all,
32       of  the  named  diagnostic  pages  are defined in the SES standards and
33       drafts. The most recent reference for this utility is  the  draft  SCSI
34       Enclosure    Services    3   document   T10/2149-D   Revision   11   at
35       http://www.t10.org . Existing standards for  SES  and  SES-2  are  ANSI
36       INCITS 305-1998 and ANSI INCITS 448-2008 respectively.
37
38       The first form shown in the synopsis is for fetching and decoding pages
39       or fields from the SES DEVICE. Alternatively a fetched page may be out‐
40       put in hex or binary with the --hex or --raw options.
41
42       The  second  form in the synopsis is for modifying pages or fields held
43       in the SES DEVICE. Changing the state of an enclosure (e.g.  requesting
44       the  "ident"  (locate)  LED  to flash on a disk carrier in an array) is
45       typically done using a read-modify-write  cycle.  See  the  section  on
46       CHANGING STATE below.
47
48       The  third form in the synopsis shows the options for providing command
49       line help (i.e. usage information), listing out page and field informa‐
50       tion  tables held by the utility (--enumerate), or printing the version
51       string of this utility.
52
53       There    is    a    web    page    discussing    this    utility     at
54       http://sg.danny.cz/sg/sg_ses.html  .  Support for downloading microcode
55       to  a  SES  device  has  been  placed  in  a  separate  utility  called
56       sg_ses_microcode.
57
58       In  the  following  sections "page" refers to a diagnostic page, either
59       fetched with a SCSI RECEIVE DIAGNOSTIC RESULTS command or sent  to  the
60       DEVICE with a SCSI SEND DIAGNOSTIC command.
61

OPTIONS

63       Arguments to long options are mandatory for short options as well.  The
64       options are arranged in alphabetical order based  on  the  long  option
65       name.
66
67       -b, --byte1=B1
68              some  modifiable  pages  may  need byte 1 (i.e. the second byte)
69              set. In the Enclosure Control page, byte 1  contains  the  INFO,
70              NON-CRIT, CRIT and UNRECOV bits. In the Subenclosure String Out,
71              Subenclosure Nickname Control  and  Download  Microcode  Control
72              pages,  byte  1 is the Subenclosure identifier.  Active when the
73              --control and --data=H,H... options are  used  and  the  default
74              value  is 0. If the --clear=STR or --set=STR option is used then
75              the value read from byte 1 is written back to byte 1.  B1 is  in
76              decimal unless it is prefixed by '0x' or '0X' (or has a trailing
77              'h' or 'H').
78
79       -C, --clear=STR
80              Used to clear an element  field  in  the  Enclosure  Control  or
81              Threshold  Out  page.  Must  be  used  together with an indexing
82              option to specify which element is to be changed. The  Enclosure
83              Control  page  is  assumed if the --page=PG option is not given.
84              See the STR FORMAT section below.
85
86       -c, --control
87              will send control information to the  DEVICE  via  a  SCSI  SEND
88              DIAGNOSTIC  command.  Cannot give both this option and --status.
89              The Enclosure Control, String Out, Threshold Out, Array  Control
90              (obsolete in SES-2), Subenclosure String Out, Subenclosure Nick‐
91              name Control and Download Microcode pages can be set  currently.
92              This  option  is  assumed if either the --clear=STR or --set=STR
93              option is given.
94
95       -d, --data=H,H...
96              permits a string of comma separated  (ASCII)  hex  bytes  to  be
97              specified (limit 1024). A (single) space separated string of hex
98              bytes is also allowed but the list needs to be in  quotes.  This
99              option  allows the parameters to a control page to be specified.
100              The string given should not include the first 4 bytes (i.e. page
101              code and length).
102
103       -d, --data=-
104              reads  one  or  more  data strings from stdin, limit 2048 bytes.
105              stdin may provide ASCII hex as a comma separated list  (i.e.  as
106              with  the  --data=H,H...  option). Additionally spaces, tabs and
107              line feeds are permitted as separators from stdin . Stops  read‐
108              ing stdin when an EOF is detected.
109
110       -d, --data=@FN
111              reads  one  or  more data strings from the file called FN, limit
112              2048 bytes. Otherwise this option is the same  as  the  previous
113              item that reads from stdin.
114
115       -D, --descriptor=DN
116              where  DN  is a descriptor name (string) as found in the Element
117              Descriptor page. This is a medium level indexing alternative  to
118              the  low level --index= options. If the descriptor name contains
119              a space then DN needs to be surrounded by quotes (single or dou‐
120              ble)  or  the  space escaped (e.g. preceded by a backslash). See
121              the DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS  section
122              below.
123
124       -x, --dev-slot-num=SN, --dsn=SN
125              where SN is a device slot number found in the Additional Element
126              Status page. Only entries for FCP and SAS devices  (with  EIP=1)
127              have  device slot numbers. SN must be a number in the range 0 to
128              255 (inclusive). 255 is used to indicate there is no correspond‐
129              ing  device slot. This is a medium level indexing alternative to
130              the low level --index= options. See the DESCRIPTOR NAME,  DEVICE
131              SLOT NUMBER AND SAS ADDRESS section below.
132
133       -E, --eiioe=A_F
134              A_F  is  either  the  string  'auto'  or 'force'. There was some
135              fuzziness in the interpretation of the 'element index' field  in
136              the  Additional Element Status page between SES-2 and SES-3. The
137              EIIOE bit was introduced to resolve  the  problem  but  not  all
138              enclosures  have  caught  up.  Using '--eiioe=force' will decode
139              this page as if the EIIOE bit is set.  Using '--eiioe=auto' will
140              decode this page as if the EIIOE bit is set if the first element
141              index in this page is 1 (in other words  a  heuristic  to  guess
142              whether the EIIOE bit should be set or not).
143              If  the  enclosure  sets  the  EIIOE bit then this option has no
144              effect. It is recommended that HP JBOD users set --eiioe=auto .
145
146       -e, --enumerate
147              enumerate all known page names and SES elements when this option
148              is  given  once.  If --enumerate is given twice, then the recog‐
149              nised acronyms for  the  --clear=STR,  --get=STR  and  --set=STR
150              options  are listed. The utility exits after listing this infor‐
151              mation (so most other options and DEVICE are ignored).
152
153       -f, --filter
154              cuts down on the amount of output from the Enclosure Status page
155              and  the  Additional  Element  Status  page. When this option is
156              given, any line which has all its binary flags cleared (i.e.  0)
157              is filtered out (i.e.  ignored).  If a line has some other value
158              on it (e.g. a temperature) then it is output.  When this  option
159              is  used  twice  only  elements  associated with the "status=ok"
160              field (in the Enclosure status page) are  output.  The  --filter
161              option  is useful for reducing the amount of output generated by
162              the --join option.
163
164       -G, --get=STR
165              Used to read a field in a status element. Must be used  together
166              with  a  an  indexing  option  to specify which element is to be
167              read. By default the Enclosure Status page  is  read,  the  only
168              other pages that can be read are the Threshold In and Additional
169              Element Status pages. If a value is found it is output in  deci‐
170              mal to stdout (by default) or in hexadecimal preceded by "0x" if
171              the --hex option is also  given.  See  the  STR  FORMAT  section
172              below.
173
174       -h, --help
175              output  the  usage  message  then  exit. Since there is a lot of
176              information, it is split into two pages. The most  important  is
177              shown  on the first page.  Use this option twice (e.g. '-hh') to
178              output the second page. Note: the --enumerate option might  also
179              be  viewed  as a help or usage type option. And like this option
180              it has a "given twice" form: '-ee'.
181
182       -H, --hex
183              If the --get=STR option is given then output the value found (if
184              any)  in  hexadecimal, with a leading "0x". Otherwise output the
185              response in hexadecimal; with  trailing  ASCII  if  given  once,
186              without it if given twice, and simple hex if given three or more
187              times. Ignored when all elements from several  pages  are  being
188              accessed.  Also see the --raw option which may be used with this
189              option..
190
191       -I, --index=IIA
192              where IIA is either an individual index (II) or an Element  type
193              abbreviation   (A).  See  the  INDEXES  section  below.  If  the
194              --page=PG option is not given then the Enclosure Status (or Con‐
195              trol)  page  is  assumed.  May be used with the --join option or
196              one of the --clear=STR, --get=STR or --set=STR options. To  enu‐
197              merate  the  available Element type abbreviations use the --enu‐
198              merate option.
199
200       -I, --index=TIA,II
201              where TIA,II is an type header index (TI) or Element type abbre‐
202              viation  (A)  followed  by  an  individual  index  (II). See the
203              INDEXES section below. If the --page=PG option is not given then
204              the  Enclosure  Status (or Control) page is assumed. May be used
205              with the --join option or one of the --clear=STR,  --get=STR  or
206              --set=STR  options.  To  enumerate  the  available  Element type
207              abbreviations use the --enumerate option.
208
209       -i, --inner-hex
210              the outer levels of a status page are decoded  and  printed  out
211              but  the innermost level (e.g. the Element Status Descriptor) is
212              output in hex. Also active with the  Additional  Element  Status
213              and  Threshold  In  pages.  Can  be used with an indexing option
214              and/or --join options.
215
216       -j, --join
217              group elements from the Element Descriptor, Enclosure Status and
218              Additional  Element  Status pages. If this option is given twice
219              then elements from the Threshold In page are also  grouped.  The
220              order  is  dictated  by the Configuration page. All elements are
221              output unless one of the indexing options  is  given,  in  which
222              case  only  the  matching  element and its associated fields are
223              output.  The --filter option can be added to reduce  the  amount
224              of output generated by this option. See the INDEXES and DESCRIP‐
225              TOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS sections below.
226
227       -l, --list
228              This option is equivalent to --enumerate. See that option.
229
230       -M, --mask
231              When modifying elements, the default action is  a  read  (status
232              element),  mask, modify (based on --clear=STR or --set=STR) then
233              write back as the control element.  The  mask  step  is  new  in
234              sg_ses  version  1.98  and is based on what is allowable (and in
235              the same location) in draft SES-3 revision 6.  Those  masks  may
236              evolve,  as  they  have in the past. This option re-instates the
237              previous logic which was to ignore the mask  step.  The  default
238              action (i.e. without this option) is to perform the mask step in
239              the read-mask-modify-write sequence.
240
241       -m, --maxlen=LEN
242              LEN is placed in the ALLOCATION LENGTH field of the SCSI RECEIVE
243              DIAGNOSTIC  RESULTS  commands sent by the utility. It represents
244              the maximum size of data the SES device can return  (in  bytes).
245              It  cannot exceed 65535 and defaults to 65532 (bytes). Some sys‐
246              tems may not permit such large sizes hence  the  need  for  this
247              option. If LEN is set to 0 then the default size is used.
248
249       -n, --nickname=SEN
250              where  SEN  is  the new Subenclosure Nickname. Only the first 32
251              characters (bytes) of SEN are used, if more are given  they  are
252              ignored. See the SETTING SUBENCLOSURE NICKNAME section below.
253
254       -N, --nickid=SEID
255              where  SEID is the Subenclosure identifier that the new Nickname
256              (SEN) will be applied to. So SEID must be an existing  Subenclo‐
257              sure identifier. The default value is 0 which is the main enclo‐
258              sure.
259
260       -p, --page=PG
261              where PG is a page abbreviation or code (a number). If PG starts
262              with  a  digit it is assumed to be in decimal unless prefixed by
263              0x for hex. Valid range is 0 to 255  (0x0  to  0xff)  inclusive.
264              Default  is  page  'sdp'  which  is page_code 0 (i.e. "Supported
265              Diagnostic Pages") if no other options are given.
266
267       -r, --raw
268              outputs the chosen status page in ASCII hex in a format suitable
269              for a later invocation using the --data= option. A page less its
270              first 4 bytes (page code and length) is output. When used  twice
271              (e.g. -rr) the full page contents is output in binary to stdout.
272
273       -R, --readonly
274              open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag).
275              The default is to open it read-write.
276
277       -A, --sas-addr=SA
278              this is an indexing method for SAS end devices (e.g. SAS disks).
279              The  utility  will  try to find the element or slot in the Addi‐
280              tional Element Status page whose SAS address matches SA.  For  a
281              SAS  disk or tape that SAS address is its target port identifier
282              for the port connected to that element or slot.  Most SAS  disks
283              and  tapes have two such target ports, usually numbered consecu‐
284              tively.
285              SATA devices in a SAS  enclosure  often  receive  "manufactured"
286              target  port  identifiers  from a SAS expander; typically will a
287              SAS address close to but different from the SAS address  of  the
288              expander itself. Note that this manufactured target port identi‐
289              fier is different from a SATA disk's WWN.
290              SA is a hex number that is up to 8 digits long. It  may  have  a
291              leading  '0x' or '0X' or a trailing 'h' or 'H'. This option is a
292              medium level
293               indexing alternative to the low level  --index=  options.   See
294              the  DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS section
295              below.
296
297       -S, --set=STR
298              Used to set an element field in the Enclosure Control or Thresh‐
299              old  Out page.  Must be used together with an indexing option to
300              specify which element is to be changed.  The  Enclosure  Control
301              page  is  assumed  if the --page=PG option is not given. See the
302              STR FORMAT section below.
303
304       -s, --status
305              will fetch page from the DEVICE via a  SCSI  RECEIVE  DIAGNOSTIC
306              RESULTS command. In the absence of other options that imply mod‐
307              ifying a page (e.g.  --control or --set=STR)  then  --status  is
308              assumed.
309
310       -v, --verbose
311              increase the level of verbosity, (i.e. debug output).
312
313       -V, --version
314              print the version string and then exit.
315
316       -w, --warn
317              warn  about certain irregularities with warnings sent to stderr.
318              The join is a complex operation that relies on information  from
319              several  pages  to  be  synchronized. The quality of SES devices
320              vary and to be fair, the descriptions from T10 drafts and  stan‐
321              dards  have  been  tweaked  several times (see the EIIOE bit) in
322              order to clear up confusion.
323

INDEXES

325       An enclosure can have information about its disk and tape  drives  plus
326       other  supporting  components like power supplies spread across several
327       pages.  Addressing a specific element (overall or individual) within  a
328       page  is  complicated.  This section describes low level indexing (i.e.
329       choosing a single element (or a group of related elements) from a large
330       number  of elements). If available, the medium level indexing described
331       in the following section (DESCRIPTOR NAME, DEVICE SLOT NUMBER  AND  SAS
332       ADDRESS) might be simpler to use.
333
334       The Configuration page is key to low level indexing: it contains a list
335       of "type headers", each of which contains an Element type  (e.g.  Array
336       Device  Slot),  a Subenclosure identifier (0 for the primary enclosure)
337       and a "Number of possible elements". Corresponding to each type header,
338       the  Enclosure  Status  page  has one "overall" element plus "Number of
339       possible elements" individual elements all of which have the given Ele‐
340       ment  type.  For  some  Element types the "Number of possible elements"
341       will be 0 so the Enclosure Status page has only one  "overall"  element
342       corresponding  to that type header. The Element Descriptor page and the
343       Threshold (In and Out) pages follow the same pattern as  the  Enclosure
344       Status page.
345
346       The  Additional  Element  Status page is a bit more complicated. It has
347       entries for "Number of possible elements" of certain Element types.  It
348       does  not have entries corresponding to the "overall" elements. To make
349       the correspondence a  little  clearer  each  descriptor  in  this  page
350       optionally  contains an "Element Index Present" (EIP) indicator. If EIP
351       is set then each element's "Element Index" field refers to the position
352       of the corresponding element in the Enclosure Status page.
353
354       Addressing  a  single overall element or a single individual element is
355       done with two indexes: TI and II. Both are origin 0.  TI=0  corresponds
356       to  the  first  type  header entry which must be a Device Slot or Array
357       Device Slot Element type (according to the SES-2 standard). To  address
358       the  corresponding  overall instance, II is set to -1, otherwise II can
359       be set to the individual instance index. As an alternative to the  type
360       header index (TI), an Element type abbreviation (A) optionally followed
361       by a number (e.g. "ps" refers to the first Power Supply  Element  type;
362       "ps1" refers to the second) can be given.
363
364       One  of  two  command  lines  variants  can be used to specify indexes:
365       --index=TIA,II where TIA is either an type header index (TI) or an Ele‐
366       ment  type abbreviation (A) (e.g. "ps" or "ps1"). II is either an indi‐
367       vidual index or "-1" to specify the overall element. The second variant
368       is  --index=IIA where IIA is either an individual index (II) or an Ele‐
369       ment type abbreviation (A). When IIA is an individual  index  then  the
370       option  is  equivalent  to  --index=0,II.  When  IIA is an Element type
371       abbreviation then the option is equivalent to --index=A,-1.
372
373       To cope with vendor specific Element types  (which  should  be  in  the
374       range  128  to  255)  the  Element type can be given as a number with a
375       leading underscore.  For example these are equivalent: --index=arr  and
376       --index=_23 since the Array Device Slot Element type value is 23.  Also
377       --index=ps1 and --index=_2_1 are equivalent.
378
379       Another example: if the first type header in the Configuration page has
380       has  Array  Device Slot Element type then --index=0,-1 is equivalent to
381       --index=arr. Also --index=arr,3 is equivalent to --index=3.
382
383       The --index= options  can be used to reduce the amount of output  (e.g.
384       only  showing the element associated with the second 12 volt power sup‐
385       ply). They may  also  be  used  together  with  with  the  --clear=STR,
386       --get=STR  and --set=STR options which are described in the STR section
387       below.
388

DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS

390       The three options: --descriptor=DN, --dev-slot-num=SN and --sas-addr=SA
391       allow  medium  level  indexing,  as  an  alternative  to  the low level
392       --index= options. Only one of the three options can be used in an invo‐
393       cation.  Each  of  the  three  options implicitly set the --join option
394       since they need either the Element Descriptor page  or  the  Additional
395       Element Status page as well as the pages needed by the --index= option.
396
397       These  medium  level  indexing options need support from the SES device
398       and that support is optional. For example the --descriptor=DN needs the
399       Element  Descriptor  page  provided  by  the SES device however that is
400       optional. Also the provided descriptor names need  to  be  useful,  and
401       having descriptor names which are all "0" is not very useful. Also some
402       elements (e.g. overall elements) may not have descriptor names.
403
404       These medium level indexing options can be used to reduce the amount of
405       output  (e.g.  only  showing the elements related to device slot number
406       3).  They  may  also  be  used  together  with  with  the  --clear=STR,
407       --get=STR  and  --set=STR  options which are described in the following
408       section. Note that even if a field can be set  (e.g.  "do  not  remove"
409       (dnr))  and  that field can be read back with --get=STR confirming that
410       change, the disk array may still ignore it (e.g. because  it  does  not
411       have the mechanism to lock the disk drawer).
412

STR FORMAT

414       The  STR  operands  of the --clear=STR, --get=STR and --set=STR options
415       all have the same structure. There are two forms:
416             <acronym>[=<value>]
417             <start_byte>:<start_bit>[:<num_bits>][=<value>]
418
419       The <acronym> is one of a list  of  common  fields  (e.g.  "ident"  and
420       "fault") that the utility converts internally into the second form. The
421       <start_byte> is usually in the range 0 to 3, the <start_bit> must be in
422       the  range  0  to  7  and  the  <num_bits> must be in the range 1 to 64
423       (default 1). The number of bits are read in the left to right sense  of
424       the  element tables shown in the various SES draft documents. For exam‐
425       ple the 8 bits of byte 2 would be represented as 2:7:8  with  the  most
426       significant bit being 2:7 and the least significant bit being 2:0 .
427
428       The  <value>  is optional but is ignored if provided to --get=STR.  For
429       --set=STR the default <value> is 1 while for  --clear=STR  the  default
430       value  is  0 . <value> is assumed to be decimal, hexadecimal values can
431       be given in the normal fashion.
432
433       The supported list of <acronym>s can be viewed by using the --enumerate
434       option twice (or "-ee").
435

CHANGING STATE

437       This  utility  has  various  techniques for changing the state of a SES
438       device.  As noted above this  is  typically  a  read-modify-write  type
439       operation.   Most  modifiable pages have a "status" (or "in") page that
440       can be read, and a corresponding "control" (or "out") page that can  be
441       written back to change the state of the enclosure.
442
443       The  lower level technique provided by this utility involves outputting
444       a "status" page in hex with --raw. Then a text editor can  be  used  to
445       edit  the  hex  (note:  to  change  an Enclosure Control descriptor the
446       SELECT bit needs to be set). Next the control page data  can  fed  back
447       with  the  --data=H,H... option together with the --control option; the
448       --byte1=B1 option may need to be given as well.
449
450       Changes to the Enclosure Control page (and the Threshold Out page)  can
451       be  done  at a higher level. This involves choosing a page (the default
452       in this case is the Enclosure Control page). Next choose an  individual
453       or  overall  element  index  (or  name  it  with its Element Descriptor
454       string). Then give the element's name (e.g. "ident" for RQST IDENT)  or
455       its  position within that element (e.g. in an Array Device Slot Control
456       element RQST IDENT is byte 2, bit 1 and 1 bit long ("2:1:1")).  Finally
457       a  value can be given, if not the value for --set=STR defaults to 1 and
458       for --clear=STR defaults to 0.
459

SETTING SUBENCLOSURE NICKNAME

461       The format of the Subenclosure Nickname control page is different  from
462       its corresponding status page. The status page reports all Subenclosure
463       Nicknames (and Subenclosure identifier 0 is the main  enclosure)  while
464       the control page allows only one of them to be changed. Therefore using
465       the --data option technique to change a Subenclosure nickname is diffi‐
466       cult (but still possible).
467
468       To  simplify  changing  a  Subenclosure nickname the --nickname=SEN and
469       --nickid=SEID options have been added. If the SEN string contains  spa‐
470       ces  or other punctuation, it should be quoted: surrounded by single or
471       double  quotes  (or  the  offending   characters   escaped).   If   the
472       --nickid=SEID  is  not  given  then  a  Subenclosure identifier of 0 is
473       assumed. As a guard the --control option must also  be  given.  If  the
474       --page=PG option is not given then --page=snic is assumed.
475
476       When --nickname=SEN is given then the Subenclosure Nickname Status page
477       is read to obtain the  Generation  Code  field.  That  Generation  Code
478       together  with  no  more  than 32 bytes from the Nickname (SEN) and the
479       Subenclosure Identifier (SEID) are written to the Subenclosure Nickname
480       Control page.
481
482       There  is  an  example  of  changing a nickname in the EXAMPLES section
483       below.
484

NOTES

486       This utility can be used to fetch arbitrary (i.e. non  SES)  diagnostic
487       pages  (using  the  SCSI  READ  DIAGNOSTIC  command).  To  this end the
488       --page=PG and --hex options would be appropriate. Arbitrary  diagnostic
489       pages can be sent to a device with the sg_senddiag utility.
490
491       The  most  troublesome  part of the join operation is associating Addi‐
492       tional Element Status descriptors correctly. At least  one  SES  device
493       vendor  has  misinterpreted the SES-2 standard with its "element index"
494       field. The code in this utility interprets the "element index" field as
495       per  the  SES-2  standard  and  if that yields an inappropriate Element
496       type, adjusts its indexing to follow that vendor's misinterpretation.
497
498       In draft SES-3 revision 5 the "Door Lock" element name was  changed  to
499       the  "Door"  (and  an OPEN field was added to the status element). As a
500       consequence the former 'dl' element type abbreviation has been  changed
501       to 'do'.
502
503       There  is a related command set called SAF-TE (SCSI attached fault-tol‐
504       erant enclosure) for enclosure (including  RAID)  status  and  control.
505       SCSI  devices  that support SAF-TE report "Processor" peripheral device
506       type (0x3) in their INQUIRY response. See the sg_safte utility in  this
507       package or safte-monitor on the Internet.
508

EXAMPLES

510       Examples can also be found at http://sg.danny.cz/sg/sg_ses.html
511
512       The  following  examples  use  Linux  device names. For suitable device
513       names in other supported Operating Systems  see  the  sg3_utils(8)  man
514       page.
515
516       To view the supported pages:
517
518          sg_ses /dev/bsg/6:0:2:0
519
520       To view the Configuration Diagnostic page:
521
522          sg_ses --page=cf /dev/bsg/6:0:2:0
523
524       To view the Enclosure Status page:
525
526          sg_ses --page=es /dev/bsg/6:0:2:0
527
528       To  get the (attached) SAS address of that device (which is held in the
529       Additional Element Sense page (page 10)) printed on hex:
530
531          sg_ses -p aes -D ArrayDevice07 -G at_sas_addr -H /dev/sg3
532
533       To collate the information in the Enclosure Status, Element  Descriptor
534       and Additional Element Status pages the --join option can be used:
535
536          sg_ses --join /dev/sg3
537
538       This  will produce a lot of output. To filter out lines that don't con‐
539       tain much information add the --filter option:
540
541          sg_ses --join --filter /dev/sg3
542
543       Fields in the various elements of the Enclosure Control  and  Threshold
544       pages  can  be changed with the --clear=STR and --set=STR options. [All
545       modifiable pages can  be  changed  with  the  --raw  and  --data=H,H...
546       options.]  The  following example looks at making the "ident" LED (also
547       called "locate") flash on "ArrayDevice07" which is a disk (or more pre‐
548       cisely the carrier drawer the disk is in):
549
550          sg_ses --index=7 --set=2:1:1 /dev/sg3
551
552       If the Element Descriptor diagnostic page shows that "ArrayDevice07" is
553       the descriptor name associated with element index 7 then  this  invoca‐
554       tion is equivalent to the previous one:
555
556          sg_ses --descriptor=ArrayDevice07 --set=2:1:1 /dev/sg3
557
558       Further  the  byte  2, bit 1 (for 1 bit) field in the Array Device Slot
559       Control element is RQST IDENT for asking a disk carrier to flash a  LED
560       so it can be located. In this case "ident" (or "locate") is accepted as
561       an acronym for that field:
562
563          sg_ses --descriptor=ArrayDevice07 --set=ident /dev/sg3
564
565       To stop that LED flashing:
566
567          sg_ses --dev-slot-num=7 --clear=ident /dev/sg3
568
569       The above assumes the descriptor name  'ArrayDevice07'  corresponds  to
570       device slot number 7.
571
572       Now  for  an  example  of  a more general but lower level technique for
573       changing a modifiable diagnostic page. The String (In and Out) diagnos‐
574       tics page is relatively simple (compared with the Enclosure Status/Con‐
575       trol page). However the use of this lower level  technique  is  awkward
576       involving three steps: read, modify then write. First check the current
577       String (In) page contents:
578
579          sg_ses --page=str /dev/bsg/6:0:2:0
580
581       Now the "read" step. The following command will send  the  contents  of
582       the  String page (from byte 4 onwards) to stdout. The output will be in
583       ASCII hex with pairs of hex digits representing a byte,  16  pairs  per
584       line,  space  separated.  The  redirection puts stdout in a file called
585       "t":
586
587          sg_ses --page=str --raw /dev/bsg/6:0:2:0 > t
588
589       Then with the aid of the SES-3 document (in revision 3: section  6.1.6)
590       use  your  favourite editor to change t. The changes can be sent to the
591       device with:
592
593          sg_ses --page=str --control --data=- /dev/bsg/6:0:2:0 < t
594
595       If the above is successful, the String page should have  been  changed.
596       To check try:
597
598          sg_ses --page=str /dev/bsg/6:0:2:0
599
600       To change the nickname on the main enclosure:
601
602          sg_ses --nickname='1st enclosure' --control /dev/bsg/6:0:2:0
603

EXIT STATUS

605       The exit status of sg_ses is 0 when it is successful. Otherwise see the
606       sg3_utils(8) man page.
607

AUTHORS

609       Written by Douglas Gilbert.
610

REPORTING BUGS

612       Report bugs to <dgilbert at interlog dot com>.
613
615       Copyright © 2004-2015 Douglas Gilbert
616       This software is distributed under a FreeBSD license. There is NO  war‐
617       ranty;  not  even  for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
618       POSE.
619

SEE ALSO

621       sg_inq, sg_safte, sg_senddiag, sg_ses_microcode, sg3_utils (sg3_utils);
622       safte-monitor (Internet)
623
624
625
626sg3_utils-1.42                   December 2015                       SG_SES(8)
Impressum