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

INDEXES

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

DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS

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

STR FORMAT

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

CLEAR, GET, SET

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

DATA SUPPLIED

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

CHANGING STATE

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

SETTING SUBENCLOSURE NICKNAME

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

NVME ENCLOSURES

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

NOTES

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

EXAMPLES

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

EXIT STATUS

783       The exit status of sg_ses is 0 when it is successful. Otherwise see the
784       sg3_utils(8) man page.
785

AUTHORS

787       Written by Douglas Gilbert.
788

REPORTING BUGS

790       Report bugs to <dgilbert at interlog dot com>.
791
793       Copyright © 2004-2020 Douglas Gilbert
794       This software is distributed under a FreeBSD license. There is NO  war‐
795       ranty;  not  even  for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
796       POSE.
797

SEE ALSO

799       sg_inq, sg_safte, sg_senddiag, sg_ses_microcode, sg3_utils (sg3_utils);
800       safte-monitor (Internet)
801
802
803
804sg3_utils-1.45                   February 2020                       SG_SES(8)
Impressum