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  [--all]  [--descriptor=DES]  [--dev-slot-num=SN]  [--eiioe=A_F]
10       [--filter] [--get=STR] [--hex] [--index=IIA  |  --index=TIA,II]  [--in‐
11       ner-hex] [--join] [--maxlen=LEN] [--page=PG] [--quiet] [--raw] [--read‐
12       only] [--sas-addr=SA] [--status] [--verbose] [--warn] DEVICE
13
14       sg_ses    --control    [--byte1=B1]    [--clear=STR]    [--data=H,H...]
15       [--data=@FN]   [--descriptor=DES]  [--dev-slot-num=SN]  [--index=IIA  |
16       --index=TIA,II]      [--mask]      [--maxlen=LEN]      [--nickname=SEN]
17       [--nickid=SEID]   [--page=PG]  [--readonly] [--sas-addr=SA] [--set=STR]
18       [--verbose] DEVICE
19
20       sg_ses --data=@FN --status  [--raw  --raw]  [<all  options  from  first
21       form>]
22       sg_ses  --inhex=FN  --status  [--raw  --raw]  [<all  options from first
23       form>]
24
25       sg_ses [--enumerate] [--index=IIA] [--list] [--help] [--version]
26

DESCRIPTION

28       Fetches management information from a SCSI Enclosure Service (SES)  de‐
29       vice.   This utility can also modify the state of a SES device. The DE‐
30       VICE should be a SES device which may be a dedicated enclosure services
31       processor in which case an INQUIRY response's Peripheral Device Type is
32       13 [0xd]. Alternatively it may be attached to another type of SCSI  de‐
33       vice  (e.g. a disk) in which case the EncServ bit is set in its INQUIRY
34       response.
35
36       If the DEVICE argument is given with no options then the names  of  all
37       diagnostic pages (dpages) supported are listed. Most, but not necessar‐
38       ily all, of the named dpages are  defined  in  the  SES  standards  and
39       drafts.  The  most  recent reference for this utility is the draft SCSI
40       Enclosure  Services  4  document  T10/BSR  INCITS  555  Revision  5  at
41       http://www.t10.org  .  Existing  standards for SES, SES-2 and SES-3 are
42       ANSI INCITS 305-1998 and ANSI INCITS 448-2008 and ANSI INCITS  518-2017
43       respectively.
44
45       The  first  form  shown  in  the  synopsis is for fetching and decoding
46       dpages or fields from the SES DEVICE. A SCSI RECEIVE DIAGNOSTIC RESULTS
47       command  is  sent  to the DEVICE to obtain each dpage response.  Rather
48       than decoding a fetched dpage, it may be output in hex or  binary  with
49       the --hex or --raw --raw options.
50
51       The  second form in the synopsis is for modifying dpages or fields held
52       in the SES DEVICE. A SCSI SEND DIAGNOSTIC command  containing  a  "con‐
53       trol"  dpage is sent to the DEVICE to cause changes. Changing the state
54       of an enclosure (e.g. requesting the "ident" (locate) LED to flash on a
55       disk  carrier  in an array) is typically done using a read-modify-write
56       cycle.  See the section on CHANGING STATE below.
57
58       The third form in the synopsis has two  equivalent  invocations  shown.
59       They  decode the contents of a file (named FN) that holds a hexadecimal
60       or binary representation of one, or many, SES  dpage  responses.  Typi‐
61       cally  an earlier invocation of the first form of this utility with the
62       '-HHHH' option would have generated that file. Since no  SCSI  commands
63       are sent, the DEVICE argument if given will be ignored.
64
65       The  last  form in the synopsis shows the options for providing command
66       line help (i.e. usage information), listing out dpage and field  infor‐
67       mation  tables  held by the utility (--enumerate), or printing the ver‐
68       sion string of this utility.
69
70       There    is    a    web    page    discussing    this    utility     at
71       http://sg.danny.cz/sg/sg_ses.html  .  Support for downloading microcode
72       to a SES device has been placed in a separate utility called sg_ses_mi‐
73       crocode.
74
75       In  the  following sections "dpage" refers to a diagnostic page, either
76       fetched with a SCSI RECEIVE DIAGNOSTIC RESULTS command, sent to the DE‐
77       VICE with a SCSI SEND DIAGNOSTIC command, or fetched from data supplied
78       by the --data= option.
79

OPTIONS

81       Arguments to long options are mandatory for short options as well.  The
82       options  are  arranged  in  alphabetical order based on the long option
83       name.
84
85       -a, --all
86              shows (almost) all status dpages, following references and  pre‐
87              senting  the  information as a long list whose indentation indi‐
88              cates the level of nesting. This option is actually the same  as
89              --join, see its description for more information.
90
91       -b, --byte1=B1
92              some  modifiable  dpages  may need byte 1 (i.e. the second byte)
93              set. In the Enclosure Control dpage, byte 1 contains  the  INFO,
94              NON-CRIT, CRIT and UNRECOV bits. In the Subenclosure String Out,
95              Subenclosure Nickname Control  and  Download  Microcode  Control
96              dpages,  byte 1 is the Subenclosure identifier.  Active when the
97              --control and --data=H,H... options are  used  and  the  default
98              value  is 0. If the --clear=STR or --set=STR option is used then
99              the value read from byte 1 is written back to byte 1.  B1 is  in
100              decimal unless it is prefixed by '0x' or '0X' (or has a trailing
101              'h' or 'H').
102
103       -C, --clear=STR
104              Used to clear an element  field  in  the  Enclosure  Control  or
105              Threshold  Out dpage. Must be used together with an indexing op‐
106              tion to specify which element is to be  changed.  The  Enclosure
107              Control  dpage  is assumed if the --page=PG option is not given.
108              See the STR FORMAT and the CLEAR, GET, SET sections below.
109
110       -c, --control
111              will send control information to the DEVICE via a SCSI SEND  DI‐
112              AGNOSTIC  command.  Cannot  give  both this option and --status.
113              The Enclosure Control, String Out, Threshold Out, Array  Control
114              (obsolete in SES-2), Subenclosure String Out, Subenclosure Nick‐
115              name Control and Download Microcode dpages can be set currently.
116              This  option  is  assumed if either the --clear=STR or --set=STR
117              option is given.
118
119       -d, --data=H,H...
120              permits a string of comma separated  (ASCII)  hex  bytes  to  be
121              specified (limit 1024). A (single) space separated string of hex
122              bytes is also allowed but the list needs to be in  quotes.  This
123              option allows the parameters to a control dpage to be specified.
124              The string given should not include the first 4 bytes (i.e. page
125              code and length). See the DATA SUPPLIED section below.
126
127       -d, --data=-
128              reads  one  or  more data strings from stdin, limit almost 2**16
129              bytes. stdin may provide ASCII hex as  a  comma  separated  list
130              (i.e.  as  with  the --data=H,H... option). Additionally spaces,
131              tabs and line feeds are permitted as  separators  from  stdin  .
132              Stops  reading  stdin when an EOF is detected. See the DATA SUP‐
133              PLIED section below.
134
135       -d, --data=@FN
136              reads one or more data strings from the file  called  FN,  limit
137              almost  2**16  bytes. The contents of the file is decoded in the
138              same fashion as stdin described in the previous option. See  the
139              DATA SUPPLIED section below.
140
141       -D, --descriptor=DES
142              where  DES is a descriptor name (string) as found in the Element
143              Descriptor dpage. This is a medium level indexing alternative to
144              the  low level --index= options. If the descriptor name contains
145              a space then DES needs to be surrounded  by  quotes  (single  or
146              double) or the space escaped (e.g. preceded by a backslash). See
147              the DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS  section
148              below.
149
150       -x, --dev-slot-num=SN, --dsn=SN
151              where SN is a device slot number found in the Additional Element
152              Status dpage. Only entries for FCP and SAS devices (with  EIP=1)
153              have  device slot numbers. SN must be a number in the range 0 to
154              255 (inclusive). 255 is used to indicate there is no correspond‐
155              ing  device slot. This is a medium level indexing alternative to
156              the low level --index= options. See the DESCRIPTOR NAME,  DEVICE
157              SLOT NUMBER AND SAS ADDRESS section below.
158
159       -E, --eiioe=A_F
160              A_F  is  either  the  string  'auto'  or 'force'. There was some
161              fuzziness in the interpretation of the 'element index' field  in
162              the  Additional  Element  Status  (AES)  dpage between SES-2 and
163              SES-3. The EIIOE bit was introduced to resolve the  problem  but
164              not  all  enclosures  have  caught  up. In the SES-3 revision 12
165              draft the EIIOE bit was expanded to a 2 bit EIIOE field.   Using
166              '--eiioe=force'  will decode the AES dpage as if the EIIOE field
167              is set to 1.  Using '--eiioe=auto' will decode the AES dpage  as
168              if  the  EIIOE field is set to 1 if the first AES descriptor has
169              its EIP bit set and its element index field is 1 (in other words
170              a  heuristic to guess whether the EIIOE field should be set to 1
171              or 0).
172              If the enclosure sets the actual EIIOE field to 1 or  more  then
173              this  option has no effect. It is recommended that HP JBOD users
174              set --eiioe=auto .
175
176       -e, --enumerate
177              enumerate all known diagnostic page (dpage) names and  SES  ele‐
178              ments  that  this  utility recognizes plus the abbreviations ac‐
179              cepted by this utility. Ignores DEVICE if it  is  given.  Essen‐
180              tially it is dumping out tables held internally by this utility.
181              If  --enumerate is given twice, then the recognised acronyms for
182              the --clear=STR, --get=STR and --set=STR options are listed. The
183              utility  exits after listing this information, so most other op‐
184              tions and DEVICE are ignored. Since there are many acronyms  for
185              the  Enclosure  Control/Status dpage then the output can be fur‐
186              ther restricted by giving the --index=IIA option  (e.g.  "sg_ses
187              -ee  -I ts" to only show the acronyms associated with the Enclo‐
188              sure Control/Status dpage's Temperature Sensor Element Type).
189
190       -f, --filter
191              cuts down on the amount of  output  from  the  Enclosure  Status
192              dpage  and the Additional Element Status dpage. When this option
193              is given, any line which has all its binary flags cleared  (i.e.
194              0)  is  filtered  out (i.e.  ignored).  If a line has some other
195              value on it (e.g. a temperature) then it is output.   When  this
196              option  is  used  twice  only elements associated with the "sta‐
197              tus=ok" field (in the Enclosure status dpage)  are  output.  The
198              --filter option is useful for reducing the amount of output gen‐
199              erated by the --join option.
200
201       -G, --get=STR
202              Used to read a field in a status element. Must be used  together
203              with  a  an  indexing  option  to specify which element is to be
204              read. By default the Enclosure Status dpage is  read,  the  only
205              other  dpages  that  can  be read are the Threshold In and Addi‐
206              tional Element Status dpages. If a value is found it  is  output
207              in  decimal to stdout (by default) or in hexadecimal preceded by
208              "0x" if the --hex option is also given. See the STR  FORMAT  and
209              the CLEAR, GET, SET sections below.
210
211       -h, --help
212              output  the usage message then exit. Since there is a lot of in‐
213              formation, it is split into two pages.  The  most  important  is
214              shown  on the first page.  Use this option twice (e.g. '-hh') to
215              output the second page. Note: the --enumerate option might  also
216              be  viewed  as a help or usage type option. And like this option
217              it has a "given twice" form: '-ee'.
218
219       -H, --hex
220              If the --get=STR option is given then output the value found (if
221              any)  in  hexadecimal, with a leading "0x". Otherwise output the
222              response in hexadecimal; with  trailing  ASCII  if  given  once,
223              without it if given twice, and simple hex if given three or more
224              times. Ignored when all elements from several dpages  are  being
225              accessed  (e.g.  when  the  --join option is used). Also see the
226              --raw option which may be used with this option.
227              To dump one of more dpage responses to stdout in ASCII  parsable
228              hexadecimal  use  -HHH  or -HHHH. The triple H form only outputs
229              hexadecimals which is fine for a single dpage response. When all
230              dpages  are  dumped (e.g.  with --page=all) then the quad H form
231              adds the name of each dpage following a  hash  mark  ('#').  The
232              --data=  option  parser  ignores everything from and including a
233              hash mark to the end of the line. Hence the output of the quad H
234              form  is  still parsable plus it is easier for users to view and
235              possibly edit. -HHHHH (that is 5) adds the page code in hex  af‐
236              ter the page's name in the comment.
237
238       -I, --index=IIA
239              where  IIA is either an individual index (II) or an Element type
240              abbreviation  (A).  See  the  INDEXES  section  below.  If   the
241              --page=PG option is not given then the Enclosure Status (or Con‐
242              trol) dpage is assumed.  May be used with the --join  option  or
243              one  of the --clear=STR, --get=STR or --set=STR options. To enu‐
244              merate the available Element type abbreviations use  the  --enu‐
245              merate option.
246
247       -I, --index=TIA,II
248              where TIA,II is an type header index (TI) or Element type abbre‐
249              viation (A) followed by an individual index (II).  See  the  IN‐
250              DEXES  section  below. If the --page=PG option is not given then
251              the Enclosure Status (or Control) dpage is assumed. May be  used
252              with  the  --join option or one of the --clear=STR, --get=STR or
253              --set=STR options. To enumerate the available Element  type  ab‐
254              breviations use the --enumerate option.
255
256       -X, --inhex=FN
257              where  FN  is  a  filename.  It has the equivalent action of the
258              --data=@FN option. If FN is '-' then stdin is read. This  option
259              has  been  given  for compatibility with other utilities in this
260              package that use --inhex=FN (or --in=FN) is a similar  way.  See
261              the  "FORMAT  OF  FILES  CONTAINING  ASCII  HEX"  section in the
262              sg3_utils manpage for more information.
263
264       -i, --inner-hex
265              the outer levels of a status dpage are decoded and  printed  out
266              but  the innermost level (e.g. the Element Status Descriptor) is
267              output in hex. Also active with the  Additional  Element  Status
268              and  Threshold  In  dpages.  Can be used with an indexing option
269              and/or --join options.
270
271       -j, --join
272              group elements from the Element Descriptor, Enclosure Status and
273              Additional  Element Status dpages. If this option is given twice
274              then elements from the Threshold In dpage are also grouped.  The
275              order is dictated by the Configuration dpage.
276              There  can  be a bewildering amount of information in the "join"
277              output. The default is to output everything. Several  additional
278              options  are  provided  to cut down the amount displayed. If the
279              indexing options is given, only the matching elements and  their
280              associated  fields  are output. The --filter option (see its de‐
281              scription) can be added to reduce the amount  of  output.   Also
282              "--page=aes"  (or  "-p 0xa") can be added to suppress the output
283              of rows that don't have a "aes" dpage component. See the INDEXES
284              and DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS sections
285              below.
286
287       -l, --list
288              This option is equivalent to --enumerate. See that option.
289
290       -M, --mask
291              When modifying elements, the default action is  a  read  (status
292              element),  mask, modify (based on --clear=STR or --set=STR) then
293              write back as the control element.  The  mask  step  is  new  in
294              sg_ses  version  1.98  and is based on what is allowable (and in
295              the same location) in draft SES-3 revision 6.  Those  masks  may
296              evolve,  as  they  have in the past. This option re-instates the
297              previous logic which was to ignore the mask  step.  The  default
298              action (i.e. without this option) is to perform the mask step in
299              the read-mask-modify-write sequence.
300
301       -m, --maxlen=LEN
302              LEN is placed in the ALLOCATION LENGTH field of the SCSI RECEIVE
303              DIAGNOSTIC  RESULTS  commands sent by the utility. It represents
304              the maximum size of data the SES device can return  (in  bytes).
305              It  cannot exceed 65535 and defaults to 65532 (bytes). Some sys‐
306              tems may not permit such large sizes hence the need for this op‐
307              tion.  If LEN is less than 0 or greater than 65535 then an error
308              is generated. If LEN is 0 then the default value is used, other‐
309              wise  if  it is less than 4 then it is ignored (and a warning is
310              sent to stderr).
311
312       -n, --nickname=SEN
313              where SEN is the new Subenclosure Nickname. Only  the  first  32
314              characters  (bytes)  of SEN are used, if more are given they are
315              ignored. See the SETTING SUBENCLOSURE NICKNAME section below.
316
317       -N, --nickid=SEID
318              where SEID is the Subenclosure identifier that the new  Nickname
319              (SEN)  will be applied to. So SEID must be an existing Subenclo‐
320              sure identifier. The default value is 0 which is the main enclo‐
321              sure.
322
323       -p, --page=PG
324              where  PG  is  a  dpage  abbreviation  or code (a number). If PG
325              starts with a digit it is assumed to be in decimal  unless  pre‐
326              fixed  by  0x for hex. Valid range is 0 to 255 (0x0 to 0xff) in‐
327              clusive. Default is dpage 'sdp' which is page_code 0 (i.e. "Sup‐
328              ported Diagnostic Pages") if no other options are given.
329              Page code 0xff or abbreviation "all" is not a real dpage (as the
330              highest real dpage is 0x3f) but instead causes all dpages  whose
331              page  code  is  0x2f or less to be output. This can be used with
332              either the -HHHH or -rr to send either hexadecimal ASCII or  bi‐
333              nary respectively to stdout.
334              To list the available dpage abbreviations give "xxx" for PG; the
335              same information can also be found with the --enumerate option.
336
337       -q, --quiet
338              this suppresses the number of warnings and messages output.  The
339              exit status of the utility is unaffected by this option.
340
341       -r, --raw
342              outputs  the  chosen status dpage in ASCII hex in a format suit‐
343              able for a later invocation using the --data=  option.  A  dpage
344              less  its  first  4 bytes (page code and length) is output. When
345              used twice (e.g. -rr) the full dpage contents is output  in  bi‐
346              nary to stdout.
347              when  -rr  is used together with the --data=- or --data=@FN then
348              stdin or file FN is decoded as a binary stream that continues to
349              be  read until an end of file (EOF). Once that data is read then
350              the internal raw option is cleared to 0 so the output is not ef‐
351              fected. So the -rr option either changes how the input or output
352              is treated, but not both.
353
354       -R, --readonly
355              open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag).
356              The default is to open it read-write.
357
358       -A, --sas-addr=SA
359              this is an indexing method for SAS end devices (e.g. SAS disks).
360              The utility will try to find the element or slot  in  the  Addi‐
361              tional  Element Status dpage whose SAS address matches SA. For a
362              SAS disk or tape that SAS address is its target port  identifier
363              for  the port connected to that element or slot.  Most SAS disks
364              and tapes have two such target ports, usually numbered  consecu‐
365              tively.
366              SATA  devices  in  a  SAS enclosure often receive "manufactured"
367              target port identifiers from a SAS expander; typically will have
368              a  SAS  address close to, but different from, the SAS address of
369              the expander itself. Note that  this  manufactured  target  port
370              identifier is different from a SATA disk's WWN.
371              SA  is  a  hex number that is up to 8 digits long. It may have a
372              leading '0x' or '0X' or a trailing 'h' or 'H'. This option is  a
373              medium level
374               indexing  alternative  to  the low level --index= options.  See
375              the DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS  section
376              below.
377
378       -S, --set=STR
379              Used to set an element field in the Enclosure Control or Thresh‐
380              old Out dpage.  Must be used together with an indexing option to
381              specify  which  element  is to be changed. The Enclosure Control
382              dpage is assumed if the --page=PG option is not given.  See  the
383              STR FORMAT and CLEAR, GET, SET sections below.
384
385       -s, --status
386              will  fetch  dpage from the DEVICE via a SCSI RECEIVE DIAGNOSTIC
387              RESULTS command (or from --data=@FN). In the  absence  of  other
388              options  that  imply  modifying  a  dpage  (e.g.   --control  or
389              --set=STR) then --status is assumed, except when the --data= op‐
390              tion is given.  When the --data= option is given there is no de‐
391              fault action: either the --control or this option must be  given
392              to  distinguish between the two different ways that data will be
393              treated.
394
395       -v, --verbose
396              increase the level of verbosity. For example when this option is
397              given  four  times  (in which case the short form is more conve‐
398              nient: '-vvvv') then if the internal join array has been  gener‐
399              ated  then  it is output to stderr in a form suitable for debug‐
400              ging.
401
402       -V, --version
403              print the version string and then exit.
404
405       -w, --warn
406              warn about certain irregularities with warnings sent to  stderr.
407              The  join is a complex operation that relies on information from
408              several dpages to be synchronized. The quality  of  SES  devices
409              vary  and to be fair, the descriptions from T10 drafts and stan‐
410              dards have been tweaked several times (see the EIIOE  field)  in
411              order to clear up confusion.
412

INDEXES

414       An  enclosure  can have information about its disk and tape drives plus
415       other supporting components like power supplies spread  across  several
416       dpages.  Addressing a specific element (overall or individual) within a
417       dpage is complicated. This section describes low level  indexing  (i.e.
418       choosing a single element (or a group of related elements) from a large
419       number of elements). If available, the medium level indexing  described
420       in  the  following section (DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS
421       ADDRESS) might be simpler to use.
422
423       The Configuration dpage is key to low level  indexing:  it  contains  a
424       list  of  "type  headers", each of which contains an Element type (e.g.
425       Array Device Slot), a Subenclosure identifier (0 for the primary enclo‐
426       sure)  and  a "Number of possible elements". Corresponding to each type
427       header, the Enclosure Status dpage has one "overall" element plus "Num‐
428       ber  of  possible  elements"  individual elements all of which have the
429       given Element type. For some Element types the "Number of possible ele‐
430       ments"  will  be 0 so the Enclosure Status dpage has only one "overall"
431       element corresponding to that type header. The Element Descriptor dpage
432       and  the  Threshold  (In and Out) dpages follow the same pattern as the
433       Enclosure Status dpage.
434
435       The numeric index corresponding to the overall element is "-1". If  the
436       Configuration  dpage  indicates  a particular element type has "n" ele‐
437       ments and n is greater than 0 then its indexes range from 0 to n-1 .
438
439       The Additional Element Status dpage is a bit more complicated.  It  has
440       entries  for "Number of possible elements" of certain Element types. It
441       does not have entries corresponding to the "overall" elements. To  make
442       the  correspondence  a little clearer each descriptor in this dpage op‐
443       tionally contains an "Element Index Present" (EIP) indicator. If EIP is
444       set then each element's "Element Index" field refers to the position of
445       the corresponding element in the Enclosure Status dpage.
446
447       Addressing a single overall element or a single individual  element  is
448       done  with  two indexes: TI and II. Both are origin 0. TI=0 corresponds
449       to the first type header entry which must be a Device Slot or Array De‐
450       vice  Slot  Element  type (according to the SES-2 standard). To address
451       the corresponding overall instance, II is set to -1, otherwise  II  can
452       be  set to the individual instance index. As an alternative to the type
453       header index (TI), an Element type abbreviation (A) optionally followed
454       by  a  number (e.g. "ps" refers to the first Power Supply Element type;
455       "ps1" refers to the second) can be given.
456
457       One of two command lines variants can be used to specify indexes: --in‐
458       dex=TIA,II  where TIA is either an type header index (TI) or an Element
459       type abbreviation (A) (e.g. "ps" or "ps1"). II is either an  individual
460       index  or  "-1"  to  specify the overall element. The second variant is
461       --index=IIA where IIA is either an individual index (II) or an  Element
462       type  abbreviation (A). When IIA is an individual index then the option
463       is equivalent to --index=0,II. When IIA is an Element type abbreviation
464       then the option is equivalent to --index=A,-1.
465
466       Wherever  an  individual  index is applicable, it can be replaced by an
467       individual index range. It has the form: <first_ii>-<last_ii>. For  ex‐
468       ample: '3-5' will select individual indexes 3, 4 and 5 .
469
470       To  cope with vendor specific Element types (whose type codes should be
471       in the range 128 to 255) the Element type code can be given as a number
472       with  a  leading  underscore.  For  example these are equivalent: --in‐
473       dex=arr and --index=_23 since the Array Device Slot Element  type  code
474       is 23.  Also --index=ps1 and --index=_2_1 are equivalent.
475
476       Another  example:  if  the first type header in the Configuration dpage
477       has has Array Device Slot Element type then --index=0,-1 is  equivalent
478       to --index=arr. Also --index=arr,3 is equivalent to --index=3.
479
480       The  --index= options  can be used to reduce the amount of output (e.g.
481       only showing the element associated with the second 12 volt power  sup‐
482       ply).  They  may  also  be  used  together  with  with the --clear=STR,
483       --get=STR and --set=STR options which are described in the STR  section
484       below.
485

DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS

487       The    three    options:    --descriptor=DES,   --dev-slot-num=SN   and
488       --sas-addr=SA allow medium level indexing, as an alternative to the low
489       level --index= options. Only one of the three options can be used in an
490       invocation. Each of the three options implicitly set the --join  option
491       since  they  need either the Element Descriptor dpage or the Additional
492       Element Status dpage as well as the dpages needed by the  --index=  op‐
493       tion.
494
495       These  medium  level  indexing options need support from the SES device
496       and that support is optional. For example  the  --descriptor=DES  needs
497       the Element Descriptor dpage provided by the SES device however that is
498       optional. Also the provided descriptor names need  to  be  useful,  and
499       having descriptor names which are all "0" is not very useful. Also some
500       elements (e.g. overall elements) may not have descriptor names.
501
502       These medium level indexing options can be used to reduce the amount of
503       output  (e.g.  only  showing the elements related to device slot number
504       3).  They  may  also  be  used  together  with  with  the  --clear=STR,
505       --get=STR  and  --set=STR  options which are described in the following
506       section. Note that even if a field can be set  (e.g.  "do  not  remove"
507       (dnr))  and  that field can be read back with --get=STR confirming that
508       change, the disk array may still ignore it (e.g. because  it  does  not
509       have the mechanism to lock the disk drawer).
510

STR FORMAT

512       The  STR  operands  of the --clear=STR, --get=STR and --set=STR options
513       all have the same structure. There are two forms:
514             <acronym>[=<value>]
515             <start_byte>:<start_bit>[:<num_bits>][=<value>]
516
517       The <acronym> is one of a list  of  common  fields  (e.g.  "ident"  and
518       "fault") that the utility converts internally into the second form. The
519       <start_byte> is usually in the range 0 to 3, the <start_bit> must be in
520       the  range  0 to 7 and the <num_bits> must be in the range 1 to 64 (de‐
521       fault 1). The number of bits are read in the left to right sense of the
522       element  tables  shown  in the various SES draft documents. For example
523       the 8 bits of byte 2 would be represented as 2:7:8 with the  most  sig‐
524       nificant bit being 2:7 and the least significant bit being 2:0 .
525
526       The  <value>  is optional but is ignored if provided to --get=STR.  For
527       --set=STR the default <value> is 1 while for  --clear=STR  the  default
528       value  is  0 . <value> is assumed to be decimal, hexadecimal values can
529       be given in the normal fashion.
530
531       The supported list of <acronym>s can be viewed by using the --enumerate
532       option twice (or "-ee").
533

CLEAR, GET, SET

535       The  --clear=STR,  --get=STR  and --set=STR options can be used up to 8
536       times in the same invocation. Any <acronym>s used in the  STR  operands
537       must refer to the same dpage.
538
539       When  multiple of these options are used (maximum: 8), they are applied
540       in the order in which they appear on the command line.  So  if  options
541       contradict  each other, the last one appearing on the command line will
542       be enforced. When there are multiple --clear=STR and --set=STR options,
543       then the dpage they refer to is only written after the last one.
544

DATA SUPPLIED

546       This  section  describes  the  two  scenarios  that  can occur when the
547       --data= option is given. These scenarios are the same  irrespective  of
548       whether  the argument to the --data= option is a string of hex bytes on
549       the command line, stdin (indicated by --data=-) or names a  file  (e.g.
550       --data=@thresh_in_dpage.hex).
551
552       The first scenario is flagged by the --control option. It uses the sup‐
553       plied data to build a 'control' dpage that will be sent to  the  DEVICE
554       using  the  SCSI  SCSI SEND DIAGNOSTIC command. The supplied dpage data
555       should not include its first 4 bytes. Those 4 bytes are added  by  this
556       utility using the --page=PG option with PG placed at byte offset 0). If
557       needed, the --byte1=B1 option sets byte offset 1, else 0 is  placed  in
558       that position. The number of bytes decoded from the data provided (i.e.
559       its length) goes into byte offsets 2 and 3.
560
561       The second scenario is flagged by the --status option. It  decodes  the
562       supplied  data  assuming that it represents the response to one or more
563       SCSI RECEIVE DIAGNOSTIC RESULTS commands. Those  responses  have  typi‐
564       cally  been  captured  from some earlier invocation(s) of this utility.
565       Those earlier invocations could use the '-HHH' or  '-HHHH'  option  and
566       file  redirection  to capture that response (or responses) in hexadeci‐
567       mal. The supplied dpage response data is decoded according to the other
568       command  line options. For example the --join option could be given and
569       that would require the data from multiple dpages typically:  Configura‐
570       tion,  Enclosure status, Element descriptor and Additional element sta‐
571       tus dpages. If in doubt use --page=all in  the  capture  phase;  having
572       more dpages than needed is not a problem.
573
574       By default the user supplied data is assumed to be ASCII hexadecimal in
575       lines that don't exceed 512 characters. Anything on a line from and in‐
576       cluding a hash mark ('#') to the end of line is ignored. An end of line
577       can be a LF or CR,LF and blank lines are ignored. Each  separated  pair
578       (or  single) hexadecimal digits represent a byte (and neither a leading
579       '0x' nor a trailing 'h' should be given). Separators are either  space,
580       tab, comma or end of line.
581
582       Alternatively  binary  can be used and this is flagged by the '-rr' op‐
583       tion.  The --data=H,H... form cannot use binary values  for  the  'H's,
584       only  ASCII  hexadecimal. The other two forms (--data=- and --data=@FN)
585       may contain binary data. Note that when the '-rr' option is  used  with
586       --data=@FN  that  it only changes the interpretation of the input data,
587       it does not change the decoding and output representation.
588

CHANGING STATE

590       This utility has various techniques for changing the state of a SES de‐
591       vice.  As noted above this is typically a read-modify-write type opera‐
592       tion.  Most modifiable dpages have a "status" (or "in") page  that  can
593       be  read,  and  a  corresponding "control" (or "out") dpage that can be
594       written back to change the state of the enclosure.
595
596       The lower level technique provided by this utility involves  outputting
597       a  "status"  dpage in hex with --raw. Then a text editor can be used to
598       edit the hex (note: to change an Enclosure Control descriptor  the  SE‐
599       LECT  bit  needs  to  be set). Next the control dpage data can fed back
600       with the --data=H,H... option together with the --control  option;  the
601       --byte1=B1 option may need to be given as well.
602
603       Changes  to  the  Enclosure Control dpage (and the Threshold Out dpage)
604       can be done at a higher level. This involves choosing a dpage (the  de‐
605       fault  in this case is the Enclosure Control dpage). Next choose an in‐
606       dividual or overall element index (or name it with its Element Descrip‐
607       tor string). Then give the element's name (e.g. "ident" for RQST IDENT)
608       or its position within that element (e.g. in an Array Device Slot  Con‐
609       trol element RQST IDENT is byte 2, bit 1 and 1 bit long ("2:1:1")). Fi‐
610       nally a value can be given, if not the value for --set=STR defaults  to
611       1 and for --clear=STR defaults to 0.
612

SETTING SUBENCLOSURE NICKNAME

614       The format of the Subenclosure Nickname control dpage is different from
615       its corresponding status dpage. The status dpage reports all  Subenclo‐
616       sure  Nicknames  (and  Subenclosure identifier 0 is the main enclosure)
617       while the control dpage allows only one of them to be  changed.  There‐
618       fore  using  the --data option technique to change a Subenclosure nick‐
619       name is difficult (but still possible).
620
621       To simplify changing a Subenclosure  nickname  the  --nickname=SEN  and
622       --nickid=SEID  options have been added. If the SEN string contains spa‐
623       ces or other punctuation, it should be quoted: surrounded by single  or
624       double   quotes   (or   the   offending  characters  escaped).  If  the
625       --nickid=SEID is not given then a Subenclosure identifier of 0  is  as‐
626       sumed.  As  a  guard  the  --control  option must also be given. If the
627       --page=PG option is not given then --page=snic is assumed.
628
629       When --nickname=SEN is given  then  the  Subenclosure  Nickname  Status
630       dpage is read to obtain the Generation Code field. That Generation Code
631       together with no more than 32 bytes from the  Nickname  (SEN)  and  the
632       Subenclosure Identifier (SEID) are written to the Subenclosure Nickname
633       Control dpage.
634
635       There is an example of changing a nickname in the EXAMPLES section  be‐
636       low.
637

NVME ENCLOSURES

639       Support has been added to sg_ses (actually, its underlying library) for
640       NVMe (also known as NVM Express) Enclosures. It can be  considered  ex‐
641       perimental in sg3_utils package version 1.43 and sg_ses version 2.34 .
642
643       This  support  is based on a decision by NVME-MI (Management Interface)
644       developers to support the  SES-3  standard.  This  was  facilitated  by
645       adding NVME-MI SES Send and SES Receive commands that tunnel dpage con‐
646       tents as used by SES.
647

NOTES

649       This utility can be used to fetch arbitrary (i.e. non SES) dpages  (us‐
650       ing  the  SCSI  READ DIAGNOSTIC command). To this end the --page=PG and
651       --hex options would be appropriate. Non-SES dpages can be sent to a de‐
652       vice with the sg_senddiag utility.
653
654       The  most  troublesome  part of the join operation is associating Addi‐
655       tional Element Status descriptors correctly. At least  one  SES  device
656       vendor  has  misinterpreted  the  SES-2 standard, specifically with its
657       "element index" field interpretation. The code in this  utility  inter‐
658       prets  the  "element index" field as per the SES-2 standard and if that
659       yields an inappropriate Element type, adjusts its  indexing  to  follow
660       that  vendor's  misinterpretation. The SES-3 drafts have introduced the
661       EIIOE (Element Index Includes Overall Elements) bit which later  became
662       a 2 bit field to resolve this ambiguity. See the --eiioe=A_F option.
663
664       In  draft  SES-3 revision 5 the "Door Lock" element name was changed to
665       the "Door" (and an OPEN field was added to the status  element).  As  a
666       consequence  the former 'dl' element type abbreviation has been changed
667       to 'do'.
668
669       There is a related command set called SAF-TE (SCSI attached  fault-tol‐
670       erant  enclosure)  for  enclosure  (including RAID) status and control.
671       SCSI devices that support SAF-TE report "Processor"  peripheral  device
672       type  (0x3) in their INQUIRY response. See the sg_safte utility in this
673       package or the safte-monitor utility on the Internet.
674
675       The internal join array is statically allocated and its  size  is  con‐
676       trolled by the MX_JOIN_ROWS define. Its current value is 520.
677

EXAMPLES

679       Examples can also be found at http://sg.danny.cz/sg/sg_ses.html
680
681       The  following  examples  use  Linux  device names. For suitable device
682       names in other supported Operating Systems  see  the  sg3_utils(8)  man
683       page.
684
685       To view the supported dpages:
686
687          sg_ses /dev/bsg/6:0:2:0
688
689       To view the Configuration Diagnostic dpage:
690
691          sg_ses --page=cf /dev/bsg/6:0:2:0
692
693       To view the Enclosure Status dpage:
694
695          sg_ses --page=es /dev/bsg/6:0:2:0
696
697       To  get the (attached) SAS address of that device (which is held in the
698       Additional Element Sense dpage (dpage 10)) printed on hex:
699
700          sg_ses -p aes -D ArrayDevice07 -G at_sas_addr -H /dev/sg3
701
702       To collate the information in the Enclosure Status, Element  Descriptor
703       and Additional Element Status dpages the --join option can be used:
704
705          sg_ses --join /dev/sg3
706
707       This  will produce a lot of output. To filter out lines that don't con‐
708       tain much information add the --filter option:
709
710          sg_ses --join --filter /dev/sg3
711
712       Fields in the various elements of the Enclosure Control  and  Threshold
713       dpages  can be changed with the --clear=STR and --set=STR options. [All
714       modifiable dpages can be changed with the --raw and  --data=H,H...  op‐
715       tions.]  The  following  example  looks at making the "ident" LED (also
716       called "locate") flash on "ArrayDevice07" which is a disk (or more pre‐
717       cisely the carrier drawer the disk is in):
718
719          sg_ses --index=7 --set=2:1:1 /dev/sg3
720
721       If  the  Element Descriptor diagnostic dpage shows that "ArrayDevice07"
722       is the descriptor name associated with element index 7 then this  invo‐
723       cation is equivalent to the previous one:
724
725          sg_ses --descriptor=ArrayDevice07 --set=2:1:1 /dev/sg3
726
727       Further  the  byte  2, bit 1 (for 1 bit) field in the Array Device Slot
728       Control element is RQST IDENT for asking a disk carrier to flash a  LED
729       so it can be located. In this case "ident" (or "locate") is accepted as
730       an acronym for that field:
731
732          sg_ses --descriptor=ArrayDevice07 --set=ident /dev/sg3
733
734       To stop that LED flashing:
735
736          sg_ses --dev-slot-num=7 --clear=ident /dev/sg3
737
738       The above assumes the descriptor name  'ArrayDevice07'  corresponds  to
739       device slot number 7.
740
741       Now  for  an  example  of  a more general but lower level technique for
742       changing a modifiable diagnostic dpage. The String (In and  Out)  diag‐
743       nostics  dpage  is  relatively simple (compared with the Enclosure Sta‐
744       tus/Control dpage). However the use of this lower  level  technique  is
745       awkward involving three steps: read, modify then write. First check the
746       current String (In) dpage contents:
747
748          sg_ses --page=str /dev/bsg/6:0:2:0
749
750       Now the "read" step. The following command will send  the  contents  of
751       the String dpage (from byte 4 onwards) to stdout. The output will be in
752       ASCII hex with pairs of hex digits representing a byte,  16  pairs  per
753       line,  space  separated.  The  redirection puts stdout in a file called
754       "t":
755
756          sg_ses --page=str --raw /dev/bsg/6:0:2:0 > t
757
758       Then with the aid of the SES-3 document (in revision 3: section  6.1.6)
759       use  your  favourite editor to change t. The changes can be sent to the
760       device with:
761
762          sg_ses --page=str --control --data=- /dev/bsg/6:0:2:0 < t
763
764       If the above is successful, the String dpage should have been  changed.
765       To check try:
766
767          sg_ses --page=str /dev/bsg/6:0:2:0
768
769       To change the nickname on the main enclosure:
770
771          sg_ses --nickname='1st enclosure' --control /dev/bsg/6:0:2:0
772
773       To capture the whole state of an enclosure (from a SES perspective) for
774       later analysis, this can be done:
775
776          sg_ses --page=all -HHHH /dev/sg5 > enc_sg5_all.hex
777
778       Note that if there are errors or warnings they will be sent  to  stderr
779       so  they  will  appear  on the command line (since only stdout is redi‐
780       rected).  A text editor could be used to inspect enc_sg5_all.hex  .  If
781       all  looks  in order at some later time, potentially on a different ma‐
782       chine where enc_sg5_all.hex has been copied, a "join"  could  be  done.
783       Note that join reflects the state of the enclosure when the capture was
784       done.
785
786          sg_ses --data=@enc_sg5_all.hex --status --join
787

EXIT STATUS

789       The exit status of sg_ses is 0 when it is successful. Otherwise see the
790       sg3_utils(8) man page.
791

AUTHORS

793       Written by Douglas Gilbert.
794

REPORTING BUGS

796       Report bugs to <dgilbert at interlog dot com>.
797
799       Copyright © 2004-2021 Douglas Gilbert
800       This  software is distributed under a FreeBSD license. There is NO war‐
801       ranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR  PUR‐
802       POSE.
803

SEE ALSO

805       sg_inq, sg_safte, sg_senddiag, sg_ses_microcode, sg3_utils (sg3_utils);
806       safte-monitor (Internet)
807
808
809
810sg3_utils-1.46                   February 2021                       SG_SES(8)
Impressum