sg_ses - access a SCSI Enclosure Services (SES) device
sg_ses [--all] [--descriptor=DES] [--dev-slot-num=SN] [--eiioe=A_F] [--filter] [--get=STR] [--hex] [--index=IIA | --index=TIA,II] [--inner-hex] [--join] [--maxlen=LEN] [--page=PG] [--quiet] [--raw] [--readonly] [--sas-addr=SA] [--status] [--verbose] [--warn] DEVICE sg_ses --control [--byte1=B1] [--clear=STR] [--data=H,H...] [--data=@FN] [--descriptor=DES] [--dev-slot-num=SN] [--index=IIA | --index=TIA,II] [--mask] [--maxlen=LEN] [--nickname=SEN] [--nickid=SEID] [--page=PG] [--readonly] [--sas-addr=SA] [--set=STR] [--verbose] DEVICE sg_ses --data=@FN --status [--raw --raw] [<all options from first form>] sg_ses --inhex=FN --status [--raw --raw] [<all options from first form>] sg_ses [--enumerate] [--index=IIA] [--list] [--help] [--version]
SG_SES(8) SG3_UTILS SG_SES(8)
NAME
sg_ses - access a SCSI Enclosure Services (SES) device
SYNOPSIS
sg_ses [--all] [--descriptor=DES] [--dev-slot-num=SN] [--eiioe=A_F]
[--filter] [--get=STR] [--hex] [--index=IIA | --index=TIA,II]
[--inner-hex] [--join] [--maxlen=LEN] [--page=PG] [--quiet] [--raw]
[--readonly] [--sas-addr=SA] [--status] [--verbose] [--warn] DEVICE
sg_ses --control [--byte1=B1] [--clear=STR] [--data=H,H...]
[--data=@FN] [--descriptor=DES] [--dev-slot-num=SN] [--index=IIA |
--index=TIA,II] [--mask] [--maxlen=LEN] [--nickname=SEN]
[--nickid=SEID] [--page=PG] [--readonly] [--sas-addr=SA] [--set=STR]
[--verbose] DEVICE
sg_ses --data=@FN --status [--raw --raw] [<all options from first
form>]
sg_ses --inhex=FN --status [--raw --raw] [<all options from first
form>]
sg_ses [--enumerate] [--index=IIA] [--list] [--help] [--version]
DESCRIPTION
Fetches management information from a SCSI Enclosure Service (SES)
device. This utility can also modify the state of a SES device. The
DEVICE should be a SES device which may be a dedicated enclosure ser-
vices processor in which case an INQUIRY response's Peripheral Device
Type is 13 [0xd]. Alternatively it may be attached to another type of
SCSI device (e.g. a disk) in which case the EncServ bit is set in its
INQUIRY response.
If the DEVICE argument is given with no options then the names of all
diagnostic pages (dpages) supported are listed. Most, but not necessar-
ily all, of the named dpages are defined in the SES standards and
drafts. The most recent reference for this utility is the draft SCSI
Enclosure Services 4 document T10/BSR INCITS 555 Revision 5 at
http://www.t10.org . Existing standards for SES, SES-2 and SES-3 are
ANSI INCITS 305-1998 and ANSI INCITS 448-2008 and ANSI INCITS 518-2017
respectively.
The first form shown in the synopsis is for fetching and decoding
dpages or fields from the SES DEVICE. A SCSI RECEIVE DIAGNOSTIC RESULTS
command is sent to the DEVICE to obtain each dpage response. Rather
than decoding a fetched dpage, it may be output in hex or binary with
the --hex or --raw --raw options.
The second form in the synopsis is for modifying dpages or fields held
in the SES DEVICE. A SCSI SEND DIAGNOSTIC command containing a "con-
trol" dpage is sent to the DEVICE to cause changes. Changing the state
of an enclosure (e.g. requesting the "ident" (locate) LED to flash on a
disk carrier in an array) is typically done using a read-modify-write
cycle. See the section on CHANGING STATE below.
The third form in the synopsis has two equivalent invocations shown.
They decode the contents of a file (named FN) that holds a hexadecimal
or binary representation of one, or many, SES dpage responses. Typi-
cally an earlier invocation of the first form of this utility with the
'-HHHH' option would have generated that file. Since no SCSI commands
are sent, the DEVICE argument if given will be ignored.
The last form in the synopsis shows the options for providing command
line help (i.e. usage information), listing out dpage and field infor-
mation tables held by the utility (--enumerate), or printing the ver-
sion string of this utility.
There is a web page discussing this utility at
http://sg.danny.cz/sg/sg_ses.html . Support for downloading microcode
to a SES device has been placed in a separate utility called
sg_ses_microcode.
In the following sections "dpage" refers to a diagnostic page, either
fetched with a SCSI RECEIVE DIAGNOSTIC RESULTS command, sent to the
DEVICE with a SCSI SEND DIAGNOSTIC command, or fetched from data sup-
plied by the --data= option.
OPTIONS
Arguments to long options are mandatory for short options as well. The
options are arranged in alphabetical order based on the long option
name.
-a, --all
shows (almost) all status dpages, following references and pre-
senting the information as a long list whose indentation indi-
cates the level of nesting. This option is actually the same as
--join, see its description for more information.
-b, --byte1=B1
some modifiable dpages may need byte 1 (i.e. the second byte)
set. In the Enclosure Control dpage, byte 1 contains the INFO,
NON-CRIT, CRIT and UNRECOV bits. In the Subenclosure String Out,
Subenclosure Nickname Control and Download Microcode Control
dpages, byte 1 is the Subenclosure identifier. Active when the
--control and --data=H,H... options are used and the default
value is 0. If the --clear=STR or --set=STR option is used then
the value read from byte 1 is written back to byte 1. B1 is in
decimal unless it is prefixed by '0x' or '0X' (or has a trailing
'h' or 'H').
-C, --clear=STR
Used to clear an element field in the Enclosure Control or
Threshold Out dpage. Must be used together with an indexing
option to specify which element is to be changed. The Enclosure
Control dpage is assumed if the --page=PG option is not given.
See the STR FORMAT and the CLEAR, GET, SET sections below.
-c, --control
will send control information to the DEVICE via a SCSI SEND
DIAGNOSTIC command. Cannot give both this option and --status.
The Enclosure Control, String Out, Threshold Out, Array Control
(obsolete in SES-2), Subenclosure String Out, Subenclosure Nick-
name Control and Download Microcode dpages can be set currently.
This option is assumed if either the --clear=STR or --set=STR
option is given.
-d, --data=H,H...
permits a string of comma separated (ASCII) hex bytes to be
specified (limit 1024). A (single) space separated string of hex
bytes is also allowed but the list needs to be in quotes. This
option allows the parameters to a control dpage to be specified.
The string given should not include the first 4 bytes (i.e. page
code and length). See the DATA SUPPLIED section below.
-d, --data=-
reads one or more data strings from stdin, limit almost 2**16
bytes. stdin may provide ASCII hex as a comma separated list
(i.e. as with the --data=H,H... option). Additionally spaces,
tabs and line feeds are permitted as separators from stdin .
Stops reading stdin when an EOF is detected. See the DATA SUP-
PLIED section below.
-d, --data=@FN
reads one or more data strings from the file called FN, limit
almost 2**16 bytes. The contents of the file is decoded in the
same fashion as stdin described in the previous option. See the
DATA SUPPLIED section below.
-D, --descriptor=DES
where DES is a descriptor name (string) as found in the Element
Descriptor dpage. This is a medium level indexing alternative to
the low level --index= options. If the descriptor name contains
a space then DES needs to be surrounded by quotes (single or
double) or the space escaped (e.g. preceded by a backslash). See
the DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS section
below.
-x, --dev-slot-num=SN, --dsn=SN
where SN is a device slot number found in the Additional Element
Status dpage. Only entries for FCP and SAS devices (with EIP=1)
have device slot numbers. SN must be a number in the range 0 to
255 (inclusive). 255 is used to indicate there is no correspond-
ing device slot. This is a medium level indexing alternative to
the low level --index= options. See the DESCRIPTOR NAME, DEVICE
SLOT NUMBER AND SAS ADDRESS section below.
-E, --eiioe=A_F
A_F is either the string 'auto' or 'force'. There was some
fuzziness in the interpretation of the 'element index' field in
the Additional Element Status (AES) dpage between SES-2 and
SES-3. The EIIOE bit was introduced to resolve the problem but
not all enclosures have caught up. In the SES-3 revision 12
draft the EIIOE bit was expanded to a 2 bit EIIOE field. Using
'--eiioe=force' will decode the AES dpage as if the EIIOE field
is set to 1. Using '--eiioe=auto' will decode the AES dpage as
if the EIIOE field is set to 1 if the first AES descriptor has
its EIP bit set and its element index field is 1 (in other words
a heuristic to guess whether the EIIOE field should be set to 1
or 0).
If the enclosure sets the actual EIIOE field to 1 or more then
this option has no effect. It is recommended that HP JBOD users
set --eiioe=auto .
-e, --enumerate
enumerate all known diagnostic page (dpage) names and SES ele-
ments that this utility recognizes plus the abbreviations
accepted by this utility. Ignores DEVICE if it is given. Essen-
tially it is dumping out tables held internally by this utility.
If --enumerate is given twice, then the recognised acronyms for
the --clear=STR, --get=STR and --set=STR options are listed. The
utility exits after listing this information, so most other
options and DEVICE are ignored. Since there are many acronyms
for the Enclosure Control/Status dpage then the output can be
further restricted by giving the --index=IIA option (e.g.
"sg_ses -ee -I ts" to only show the acronyms associated with the
Enclosure Control/Status dpage's Temperature Sensor Element
Type).
-f, --filter
cuts down on the amount of output from the Enclosure Status
dpage and the Additional Element Status dpage. When this option
is given, any line which has all its binary flags cleared (i.e.
0) is filtered out (i.e. ignored). If a line has some other
value on it (e.g. a temperature) then it is output. When this
option is used twice only elements associated with the "sta-
tus=ok" field (in the Enclosure status dpage) are output. The
--filter option is useful for reducing the amount of output gen-
erated by the --join option.
-G, --get=STR
Used to read a field in a status element. Must be used together
with a an indexing option to specify which element is to be
read. By default the Enclosure Status dpage is read, the only
other dpages that can be read are the Threshold In and Addi-
tional Element Status dpages. If a value is found it is output
in decimal to stdout (by default) or in hexadecimal preceded by
"0x" if the --hex option is also given. See the STR FORMAT and
the CLEAR, GET, SET sections below.
-h, --help
output the usage message then exit. Since there is a lot of
information, it is split into two pages. The most important is
shown on the first page. Use this option twice (e.g. '-hh') to
output the second page. Note: the --enumerate option might also
be viewed as a help or usage type option. And like this option
it has a "given twice" form: '-ee'.
-H, --hex
If the --get=STR option is given then output the value found (if
any) in hexadecimal, with a leading "0x". Otherwise output the
response in hexadecimal; with trailing ASCII if given once,
without it if given twice, and simple hex if given three or more
times. Ignored when all elements from several dpages are being
accessed (e.g. when the --join option is used). Also see the
--raw option which may be used with this option.
To dump one of more dpage responses to stdout in ASCII parsable
hexadecimal use -HHH or -HHHH. The triple H form only outputs
hexadecimals which is fine for a single dpage response. When all
dpages are dumped (e.g. with --page=all) then the quad H form
adds the name of each dpage following a hash mark ('#'). The
--data= option parser ignores everything from and including a
hash mark to the end of the line. Hence the output of the quad H
form is still parsable plus it is easier for users to view and
possibly edit. -HHHHH (that is 5) adds the page code in hex
after the page's name in the comment.
-I, --index=IIA
where IIA is either an individual index (II) or an Element type
abbreviation (A). See the INDEXES section below. If the
--page=PG option is not given then the Enclosure Status (or Con-
trol) dpage is assumed. May be used with the --join option or
one of the --clear=STR, --get=STR or --set=STR options. To enu-
merate the available Element type abbreviations use the --enu-
merate option.
-I, --index=TIA,II
where TIA,II is an type header index (TI) or Element type abbre-
viation (A) followed by an individual index (II). See the
INDEXES section below. If the --page=PG option is not given then
the Enclosure Status (or Control) dpage is assumed. May be used
with the --join option or one of the --clear=STR, --get=STR or
--set=STR options. To enumerate the available Element type
abbreviations use the --enumerate option.
-X, --inhex=FN
where FN is a filename. It has the equivalent action of the
--data=@FN option. If FN is '-' then stdin is read. This option
has been given for compatibility with other utilities in this
package that use --inhex=FN (or --in=FN) is a similar way. See
the "FORMAT OF FILES CONTAINING ASCII HEX" section in the
sg3_utils manpage for more information.
-i, --inner-hex
the outer levels of a status dpage are decoded and printed out
but the innermost level (e.g. the Element Status Descriptor) is
output in hex. Also active with the Additional Element Status
and Threshold In dpages. Can be used with an indexing option
and/or --join options.
-j, --join
group elements from the Element Descriptor, Enclosure Status and
Additional Element Status dpages. If this option is given twice
then elements from the Threshold In dpage are also grouped. The
order is dictated by the Configuration dpage.
There can be a bewildering amount of information in the "join"
output. The default is to output everything. Several additional
options are provided to cut down the amount displayed. If the
indexing options is given, only the matching elements and their
associated fields are output. The --filter option (see its
description) can be added to reduce the amount of output. Also
"--page=aes" (or "-p 0xa") can be added to suppress the output
of rows that don't have a "aes" dpage component. See the INDEXES
and DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS sections
below.
-l, --list
This option is equivalent to --enumerate. See that option.
-M, --mask
When modifying elements, the default action is a read (status
element), mask, modify (based on --clear=STR or --set=STR) then
write back as the control element. The mask step is new in
sg_ses version 1.98 and is based on what is allowable (and in
the same location) in draft SES-3 revision 6. Those masks may
evolve, as they have in the past. This option re-instates the
previous logic which was to ignore the mask step. The default
action (i.e. without this option) is to perform the mask step in
the read-mask-modify-write sequence.
-m, --maxlen=LEN
LEN is placed in the ALLOCATION LENGTH field of the SCSI RECEIVE
DIAGNOSTIC RESULTS commands sent by the utility. It represents
the maximum size of data the SES device can return (in bytes).
It cannot exceed 65535 and defaults to 65532 (bytes). Some sys-
tems may not permit such large sizes hence the need for this
option. If LEN is less than 0 or greater than 65535 then an
error is generated. If LEN is 0 then the default value is used,
otherwise if it is less than 4 then it is ignored (and a warning
is sent to stderr).
-n, --nickname=SEN
where SEN is the new Subenclosure Nickname. Only the first 32
characters (bytes) of SEN are used, if more are given they are
ignored. See the SETTING SUBENCLOSURE NICKNAME section below.
-N, --nickid=SEID
where SEID is the Subenclosure identifier that the new Nickname
(SEN) will be applied to. So SEID must be an existing Subenclo-
sure identifier. The default value is 0 which is the main enclo-
sure.
-p, --page=PG
where PG is a dpage abbreviation or code (a number). If PG
starts with a digit it is assumed to be in decimal unless pre-
fixed by 0x for hex. Valid range is 0 to 255 (0x0 to 0xff)
inclusive. Default is dpage 'sdp' which is page_code 0 (i.e.
"Supported Diagnostic Pages") if no other options are given.
Page code 0xff or abbreviation "all" is not a real dpage (as the
highest real dpage is 0x3f) but instead causes all dpages whose
page code is 0x2f or less to be output. This can be used with
either the -HHHH or -rr to send either hexadecimal ASCII or
binary respectively to stdout.
To list the available dpage abbreviations give "xxx" for PG; the
same information can also be found with the --enumerate option.
-q, --quiet
this suppresses the number of warnings and messages output. The
exit status of the utility is unaffected by this option.
-r, --raw
outputs the chosen status dpage in ASCII hex in a format suit-
able for a later invocation using the --data= option. A dpage
less its first 4 bytes (page code and length) is output. When
used twice (e.g. -rr) the full dpage contents is output in
binary to stdout.
when -rr is used together with the --data=- or --data=@FN then
stdin or file FN is decoded as a binary stream that continues to
be read until an end of file (EOF). Once that data is read then
the internal raw option is cleared to 0 so the output is not
effected. So the -rr option either changes how the input or out-
put is treated, but not both.
-R, --readonly
open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag).
The default is to open it read-write.
-A, --sas-addr=SA
this is an indexing method for SAS end devices (e.g. SAS disks).
The utility will try to find the element or slot in the Addi-
tional Element Status dpage whose SAS address matches SA. For a
SAS disk or tape that SAS address is its target port identifier
for the port connected to that element or slot. Most SAS disks
and tapes have two such target ports, usually numbered consecu-
tively.
SATA devices in a SAS enclosure often receive "manufactured"
target port identifiers from a SAS expander; typically will have
a SAS address close to, but different from, the SAS address of
the expander itself. Note that this manufactured target port
identifier is different from a SATA disk's WWN.
SA is a hex number that is up to 8 digits long. It may have a
leading '0x' or '0X' or a trailing 'h' or 'H'. This option is a
medium level
indexing alternative to the low level --index= options. See
the DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS section
below.
-S, --set=STR
Used to set an element field in the Enclosure Control or Thresh-
old Out dpage. Must be used together with an indexing option to
specify which element is to be changed. The Enclosure Control
dpage is assumed if the --page=PG option is not given. See the
STR FORMAT and CLEAR, GET, SET sections below.
-s, --status
will fetch dpage from the DEVICE via a SCSI RECEIVE DIAGNOSTIC
RESULTS command (or from --data=@FN). In the absence of other
options that imply modifying a dpage (e.g. --control or
--set=STR) then --status is assumed, except when the --data=
option is given. When the --data= option is given there is no
default action: either the --control or this option must be
given to distinguish between the two different ways that data
will be treated.
-v, --verbose
increase the level of verbosity. For example when this option is
given four times (in which case the short form is more conve-
nient: '-vvvv') then if the internal join array has been gener-
ated then it is output to stderr in a form suitable for debug-
ging.
-V, --version
print the version string and then exit.
-w, --warn
warn about certain irregularities with warnings sent to stderr.
The join is a complex operation that relies on information from
several dpages to be synchronized. The quality of SES devices
vary and to be fair, the descriptions from T10 drafts and stan-
dards have been tweaked several times (see the EIIOE field) in
order to clear up confusion.
INDEXES
An enclosure can have information about its disk and tape drives plus
other supporting components like power supplies spread across several
dpages. Addressing a specific element (overall or individual) within a
dpage is complicated. This section describes low level indexing (i.e.
choosing a single element (or a group of related elements) from a large
number of elements). If available, the medium level indexing described
in the following section (DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS
ADDRESS) might be simpler to use.
The Configuration dpage is key to low level indexing: it contains a
list of "type headers", each of which contains an Element type (e.g.
Array Device Slot), a Subenclosure identifier (0 for the primary enclo-
sure) and a "Number of possible elements". Corresponding to each type
header, the Enclosure Status dpage has one "overall" element plus "Num-
ber of possible elements" individual elements all of which have the
given Element type. For some Element types the "Number of possible ele-
ments" will be 0 so the Enclosure Status dpage has only one "overall"
element corresponding to that type header. The Element Descriptor dpage
and the Threshold (In and Out) dpages follow the same pattern as the
Enclosure Status dpage.
The numeric index corresponding to the overall element is "-1". If the
Configuration dpage indicates a particular element type has "n" ele-
ments and n is greater than 0 then its indexes range from 0 to n-1 .
The Additional Element Status dpage is a bit more complicated. It has
entries for "Number of possible elements" of certain Element types. It
does not have entries corresponding to the "overall" elements. To make
the correspondence a little clearer each descriptor in this dpage
optionally contains an "Element Index Present" (EIP) indicator. If EIP
is set then each element's "Element Index" field refers to the position
of the corresponding element in the Enclosure Status dpage.
Addressing a single overall element or a single individual element is
done with two indexes: TI and II. Both are origin 0. TI=0 corresponds
to the first type header entry which must be a Device Slot or Array
Device Slot Element type (according to the SES-2 standard). To address
the corresponding overall instance, II is set to -1, otherwise II can
be set to the individual instance index. As an alternative to the type
header index (TI), an Element type abbreviation (A) optionally followed
by a number (e.g. "ps" refers to the first Power Supply Element type;
"ps1" refers to the second) can be given.
One of two command lines variants can be used to specify indexes:
--index=TIA,II where TIA is either an type header index (TI) or an Ele-
ment type abbreviation (A) (e.g. "ps" or "ps1"). II is either an indi-
vidual index or "-1" to specify the overall element. The second variant
is --index=IIA where IIA is either an individual index (II) or an Ele-
ment type abbreviation (A). When IIA is an individual index then the
option is equivalent to --index=0,II. When IIA is an Element type
abbreviation then the option is equivalent to --index=A,-1.
Wherever an individual index is applicable, it can be replaced by an
individual index range. It has the form: <first_ii>-<last_ii>. For
example: '3-5' will select individual indexes 3, 4 and 5 .
To cope with vendor specific Element types (whose type codes should be
in the range 128 to 255) the Element type code can be given as a number
with a leading underscore. For example these are equivalent:
--index=arr and --index=_23 since the Array Device Slot Element type
code is 23. Also --index=ps1 and --index=_2_1 are equivalent.
Another example: if the first type header in the Configuration dpage
has has Array Device Slot Element type then --index=0,-1 is equivalent
to --index=arr. Also --index=arr,3 is equivalent to --index=3.
The --index= options can be used to reduce the amount of output (e.g.
only showing the element associated with the second 12 volt power sup-
ply). They may also be used together with with the --clear=STR,
--get=STR and --set=STR options which are described in the STR section
below.
DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS
The three options: --descriptor=DES, --dev-slot-num=SN and
--sas-addr=SA allow medium level indexing, as an alternative to the low
level --index= options. Only one of the three options can be used in an
invocation. Each of the three options implicitly set the --join option
since they need either the Element Descriptor dpage or the Additional
Element Status dpage as well as the dpages needed by the --index=
option.
These medium level indexing options need support from the SES device
and that support is optional. For example the --descriptor=DES needs
the Element Descriptor dpage provided by the SES device however that is
optional. Also the provided descriptor names need to be useful, and
having descriptor names which are all "0" is not very useful. Also some
elements (e.g. overall elements) may not have descriptor names.
These medium level indexing options can be used to reduce the amount of
output (e.g. only showing the elements related to device slot number
3). They may also be used together with with the --clear=STR,
--get=STR and --set=STR options which are described in the following
section. Note that even if a field can be set (e.g. "do not remove"
(dnr)) and that field can be read back with --get=STR confirming that
change, the disk array may still ignore it (e.g. because it does not
have the mechanism to lock the disk drawer).
STR FORMAT
The STR operands of the --clear=STR, --get=STR and --set=STR options
all have the same structure. There are two forms:
<acronym>[=<value>]
<start_byte>:<start_bit>[:<num_bits>][=<value>]
The <acronym> is one of a list of common fields (e.g. "ident" and
"fault") that the utility converts internally into the second form. The
<start_byte> is usually in the range 0 to 3, the <start_bit> must be in
the range 0 to 7 and the <num_bits> must be in the range 1 to 64
(default 1). The number of bits are read in the left to right sense of
the element tables shown in the various SES draft documents. For exam-
ple the 8 bits of byte 2 would be represented as 2:7:8 with the most
significant bit being 2:7 and the least significant bit being 2:0 .
The <value> is optional but is ignored if provided to --get=STR. For
--set=STR the default <value> is 1 while for --clear=STR the default
value is 0 . <value> is assumed to be decimal, hexadecimal values can
be given in the normal fashion.
The supported list of <acronym>s can be viewed by using the --enumerate
option twice (or "-ee").
CLEAR, GET, SET
The --clear=STR, --get=STR and --set=STR options can be used up to 8
times in the same invocation. Any <acronym>s used in the STR operands
must refer to the same dpage.
When multiple of these options are used (maximum: 8), they are applied
in the order in which they appear on the command line. So if options
contradict each other, the last one appearing on the command line will
be enforced. When there are multiple --clear=STR and --set=STR options,
then the dpage they refer to is only written after the last one.
DATA SUPPLIED
This section describes the two scenarios that can occur when the
--data= option is given. These scenarios are the same irrespective of
whether the argument to the --data= option is a string of hex bytes on
the command line, stdin (indicated by --data=-) or names a file (e.g.
--data=@thresh_in_dpage.hex).
The first scenario is flagged by the --control option. It uses the sup-
plied data to build a 'control' dpage that will be sent to the DEVICE
using the SCSI SCSI SEND DIAGNOSTIC command. The supplied dpage data
should not include its first 4 bytes. Those 4 bytes are added by this
utility using the --page=PG option with PG placed at byte offset 0). If
needed, the --byte1=B1 option sets byte offset 1, else 0 is placed in
that position. The number of bytes decoded from the data provided (i.e.
its length) goes into byte offsets 2 and 3.
The second scenario is flagged by the --status option. It decodes the
supplied data assuming that it represents the response to one or more
SCSI RECEIVE DIAGNOSTIC RESULTS commands. Those responses have typi-
cally been captured from some earlier invocation(s) of this utility.
Those earlier invocations could use the '-HHH' or '-HHHH' option and
file redirection to capture that response (or responses) in hexadeci-
mal. The supplied dpage response data is decoded according to the other
command line options. For example the --join option could be given and
that would require the data from multiple dpages typically: Configura-
tion, Enclosure status, Element descriptor and Additional element sta-
tus dpages. If in doubt use --page=all in the capture phase; having
more dpages than needed is not a problem.
By default the user supplied data is assumed to be ASCII hexadecimal in
lines that don't exceed 512 characters. Anything on a line from and
including a hash mark ('#') to the end of line is ignored. An end of
line can be a LF or CR,LF and blank lines are ignored. Each separated
pair (or single) hexadecimal digits represent a byte (and neither a
leading '0x' nor a trailing 'h' should be given). Separators are either
space, tab, comma or end of line.
Alternatively binary can be used and this is flagged by the '-rr'
option. The --data=H,H... form cannot use binary values for the 'H's,
only ASCII hexadecimal. The other two forms (--data=- and --data=@FN)
may contain binary data. Note that when the '-rr' option is used with
--data=@FN that it only changes the interpretation of the input data,
it does not change the decoding and output representation.
CHANGING STATE
This utility has various techniques for changing the state of a SES
device. As noted above this is typically a read-modify-write type
operation. Most modifiable dpages have a "status" (or "in") page that
can be read, and a corresponding "control" (or "out") dpage that can be
written back to change the state of the enclosure.
The lower level technique provided by this utility involves outputting
a "status" dpage in hex with --raw. Then a text editor can be used to
edit the hex (note: to change an Enclosure Control descriptor the
SELECT bit needs to be set). Next the control dpage data can fed back
with the --data=H,H... option together with the --control option; the
--byte1=B1 option may need to be given as well.
Changes to the Enclosure Control dpage (and the Threshold Out dpage)
can be done at a higher level. This involves choosing a dpage (the
default in this case is the Enclosure Control dpage). Next choose an
individual or overall element index (or name it with its Element
Descriptor string). Then give the element's name (e.g. "ident" for RQST
IDENT) or its position within that element (e.g. in an Array Device
Slot Control element RQST IDENT is byte 2, bit 1 and 1 bit long
("2:1:1")). Finally a value can be given, if not the value for
--set=STR defaults to 1 and for --clear=STR defaults to 0.
SETTING SUBENCLOSURE NICKNAME
The format of the Subenclosure Nickname control dpage is different from
its corresponding status dpage. The status dpage reports all Subenclo-
sure Nicknames (and Subenclosure identifier 0 is the main enclosure)
while the control dpage allows only one of them to be changed. There-
fore using the --data option technique to change a Subenclosure nick-
name is difficult (but still possible).
To simplify changing a Subenclosure nickname the --nickname=SEN and
--nickid=SEID options have been added. If the SEN string contains spa-
ces or other punctuation, it should be quoted: surrounded by single or
double quotes (or the offending characters escaped). If the
--nickid=SEID is not given then a Subenclosure identifier of 0 is
assumed. As a guard the --control option must also be given. If the
--page=PG option is not given then --page=snic is assumed.
When --nickname=SEN is given then the Subenclosure Nickname Status
dpage is read to obtain the Generation Code field. That Generation Code
together with no more than 32 bytes from the Nickname (SEN) and the
Subenclosure Identifier (SEID) are written to the Subenclosure Nickname
Control dpage.
There is an example of changing a nickname in the EXAMPLES section
below.
NVME ENCLOSURES
Support has been added to sg_ses (actually, its underlying library) for
NVMe (also known as NVM Express) Enclosures. It can be considered
experimental in sg3_utils package version 1.43 and sg_ses version 2.34
.
This support is based on a decision by NVME-MI (Management Interface)
developers to support the SES-3 standard. This was facilitated by
adding NVME-MI SES Send and SES Receive commands that tunnel dpage con-
tents as used by SES.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+--------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+--------------------------+
|Availability | system/storage/sg3_utils |
+---------------+--------------------------+
|Stability | Pass-through uncommitted |
+---------------+--------------------------+
NOTES
This utility can be used to fetch arbitrary (i.e. non SES) dpages
(using the SCSI READ DIAGNOSTIC command). To this end the --page=PG and
--hex options would be appropriate. Non-SES dpages can be sent to a
device with the sg_senddiag utility.
The most troublesome part of the join operation is associating Addi-
tional Element Status descriptors correctly. At least one SES device
vendor has misinterpreted the SES-2 standard, specifically with its
"element index" field interpretation. The code in this utility inter-
prets the "element index" field as per the SES-2 standard and if that
yields an inappropriate Element type, adjusts its indexing to follow
that vendor's misinterpretation. The SES-3 drafts have introduced the
EIIOE (Element Index Includes Overall Elements) bit which later became
a 2 bit field to resolve this ambiguity. See the --eiioe=A_F option.
In draft SES-3 revision 5 the "Door Lock" element name was changed to
the "Door" (and an OPEN field was added to the status element). As a
consequence the former 'dl' element type abbreviation has been changed
to 'do'.
There is a related command set called SAF-TE (SCSI attached fault-tol-
erant enclosure) for enclosure (including RAID) status and control.
SCSI devices that support SAF-TE report "Processor" peripheral device
type (0x3) in their INQUIRY response. See the sg_safte utility in this
package or the safte-monitor utility on the Internet.
The internal join array is statically allocated and its size is con-
trolled by the MX_JOIN_ROWS define. Its current value is 520.
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from http://sg.danny.cz/sg/p/sg3_utils-1.46.tgz.
Further information about this software can be found on the open source
community website at http://sg.danny.cz/sg/sg3_utils.html.
EXAMPLES
Examples can also be found at http://sg.danny.cz/sg/sg_ses.html
The following examples use Linux device names. For suitable device
names in other supported Operating Systems see the sg3_utils(8) man
page.
To view the supported dpages:
sg_ses /dev/bsg/6:0:2:0
To view the Configuration Diagnostic dpage:
sg_ses --page=cf /dev/bsg/6:0:2:0
To view the Enclosure Status dpage:
sg_ses --page=es /dev/bsg/6:0:2:0
To get the (attached) SAS address of that device (which is held in the
Additional Element Sense dpage (dpage 10)) printed on hex:
sg_ses -p aes -D ArrayDevice07 -G at_sas_addr -H /dev/sg3
To collate the information in the Enclosure Status, Element Descriptor
and Additional Element Status dpages the --join option can be used:
sg_ses --join /dev/sg3
This will produce a lot of output. To filter out lines that don't con-
tain much information add the --filter option:
sg_ses --join --filter /dev/sg3
Fields in the various elements of the Enclosure Control and Threshold
dpages can be changed with the --clear=STR and --set=STR options. [All
modifiable dpages can be changed with the --raw and --data=H,H...
options.] The following example looks at making the "ident" LED (also
called "locate") flash on "ArrayDevice07" which is a disk (or more pre-
cisely the carrier drawer the disk is in):
sg_ses --index=7 --set=2:1:1 /dev/sg3
If the Element Descriptor diagnostic dpage shows that "ArrayDevice07"
is the descriptor name associated with element index 7 then this invo-
cation is equivalent to the previous one:
sg_ses --descriptor=ArrayDevice07 --set=2:1:1 /dev/sg3
Further the byte 2, bit 1 (for 1 bit) field in the Array Device Slot
Control element is RQST IDENT for asking a disk carrier to flash a LED
so it can be located. In this case "ident" (or "locate") is accepted as
an acronym for that field:
sg_ses --descriptor=ArrayDevice07 --set=ident /dev/sg3
To stop that LED flashing:
sg_ses --dev-slot-num=7 --clear=ident /dev/sg3
The above assumes the descriptor name 'ArrayDevice07' corresponds to
device slot number 7.
Now for an example of a more general but lower level technique for
changing a modifiable diagnostic dpage. The String (In and Out) diag-
nostics dpage is relatively simple (compared with the Enclosure Sta-
tus/Control dpage). However the use of this lower level technique is
awkward involving three steps: read, modify then write. First check the
current String (In) dpage contents:
sg_ses --page=str /dev/bsg/6:0:2:0
Now the "read" step. The following command will send the contents of
the String dpage (from byte 4 onwards) to stdout. The output will be in
ASCII hex with pairs of hex digits representing a byte, 16 pairs per
line, space separated. The redirection puts stdout in a file called
"t":
sg_ses --page=str --raw /dev/bsg/6:0:2:0 > t
Then with the aid of the SES-3 document (in revision 3: section 6.1.6)
use your favourite editor to change t. The changes can be sent to the
device with:
sg_ses --page=str --control --data=- /dev/bsg/6:0:2:0 < t
If the above is successful, the String dpage should have been changed.
To check try:
sg_ses --page=str /dev/bsg/6:0:2:0
To change the nickname on the main enclosure:
sg_ses --nickname='1st enclosure' --control /dev/bsg/6:0:2:0
To capture the whole state of an enclosure (from a SES perspective) for
later analysis, this can be done:
sg_ses --page=all -HHHH /dev/sg5 > enc_sg5_all.hex
Note that if there are errors or warnings they will be sent to stderr
so they will appear on the command line (since only stdout is redi-
rected). A text editor could be used to inspect enc_sg5_all.hex . If
all looks in order at some later time, potentially on a different
machine where enc_sg5_all.hex has been copied, a "join" could be done.
Note that join reflects the state of the enclosure when the capture was
done.
sg_ses --data=@enc_sg5_all.hex --status --join
EXIT STATUS
The exit status of sg_ses is 0 when it is successful. Otherwise see the
sg3_utils(8) man page.
AUTHORS
Written by Douglas Gilbert.
REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.
COPYRIGHT
Copyright (C) 2004-2021 Douglas Gilbert
This software is distributed under a FreeBSD license. There is NO war-
ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR-
POSE.
SEE ALSO
sg_inq, sg_safte, sg_senddiag, sg_ses_microcode, sg3_utils (sg3_utils);
safte-monitor (Internet)
sg3_utils-1.46 February 2021 SG_SES(8)