sg_ses man page on Alpinelinux
[printable version]
SG_SES(8) SG3_UTILS SG_SES(8)
NAME
sg_ses - access a SCSI Enclosure Services (SES) device
SYNOPSIS
sg_ses [--byte1=B1] [--clear=STR] [--control] [--data=H,H...]
[--descriptor=DN] [--dev-slot-num=SN] [--enumerate] [--filter]
[--get=STR] [--help] [--hex] [--index=IIA | --index=TIA,II]
[--inner-hex] [--join] [--list] [--nickname=SEN] [--nickid=SEID]
[--page=PG] [--raw] [--sas-addr=SA] [--set=STR] [--status] [--verbose]
[--version] DEVICE
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 no options are given (i.e. only the DEVICE argument is given) then
the names of all diagnostic pages supported are listed. Most, but not
necessarily all, of the named diagnostic pages are defined in the SES
standards and drafts. The most recent reference for this utility is the
draft SCSI Enclosure Services 3 document T10/2149-D Revision 6 at
http://www.t10.org . Existing standards for SES and SES-2 are ANSI
INCITS 305-1998 and ANSI INCITS 448-2008 respectively.
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.
There is a web page discussing this utility at
http://sg.danny.cz/sg/sg_ses.html .
In the following sections "page" refers to a diagnostic page, either
fetched with a SCSI RECEIVE DIAGNOSTIC RESULTS command or sent to the
DEVICE with a SCSI SEND DIAGNOSTIC command.
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.
-b, --byte1=B1
some modifiable pages may need byte 1 (i.e. the second byte)
set. In the Enclosure Control page, byte 1 contains the INFO,
NON-CRIT, CRIT and UNRECOV bits. In the Subenclosure String Out,
Subenclosure Nickname Control and Download Microcode Control
pages, byte 1 is the Subenclosure identifier. Active when the
--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 page. Must be used together with an indexing
option to specify which element is to be changed. The Enclosure
Control page is assumed if the --page=PG option is not given.
See the STR FORMAT section 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 pages 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 page to be specified.
The string given should not include the first 4 bytes (i.e. page
code and length).
-d, --data=-
reads one or more data strings from stdin, limit 2048 bytes.
stdin may provide ASCII hex as a comma separated list (i.e. as
with the --data=H,H... option). Additionally spaces, tabs and
line feeds are permitted as separators from stdin . Stops read‐
ing stdin when an EOF is detected.
-d, --data=@FN
reads one or more data strings from the file called FN, limit
2048 bytes. Othewise this option is the same as the previous
item that reads from stdin.
-D, --descriptor=DN
where DN is a descriptor name (string) as found in the Element
Descriptor page. This is a medium level indexing alternative to
the low level --index= options. If the descriptor name contains
a space then DN needs to be surrounded by quotes (single or dou‐
ble) or the space escaped (e.g. preceded by a backslash). See
the DESCRIPTOR NAME, DEVICE SLOT NAME AND SAS ADDRESS section
below.
-x, --dev-slot-num=SN
where SN is a device slot number found in the Additional Element
Status page. Only entries for FCP and SAS devices (with EIP=1)
have device slot numbers. SN must be a number in the range 0 to
255 (inclusive). This is a medium level indexing alternative to
the low level --index= options. See the DESCRIPTOR NAME, DEVICE
SLOT NAME AND SAS ADDRESS section below.
-e, --enumerate
enumerate all known page names and SES elements when this option
is given once. If --enumerate is given twice, then the recog‐
nised acronyms for the --clear=STR, --get=STR and --set=STR
options are listed. The utility exits after listing this infor‐
mation (so most other options and DEVICE are ignored).
-f, --filter
cuts down on the amount of output from the Enclosure Status page
and the Additional Element Status page. When this option is
given, any line which has all its binary flags cleared (i.e. 0)
is filtered out (i.e. ignored). If a line has some other value
on it (e.g. a temperature) then it is output. When this option
is used twice only elements associated with the "status=ok"
field (in the Enclosure status page) are output. The --filter
option is useful for reducing the amount of output generated 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 page is read, the only
other pages that can be read are the Threshold In and Additional
Element Status pages. If a value is found it is output in deci‐
mal to stdout (by default) or in hexadecimal preceded by "0x" if
the --hex option is also given. See the STR FORMAT section
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. Ignored when all elements from several
pages are being accessed.
-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) page 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) page 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.
-i, --inner-hex
the outer levels of a status page are decoded and printed out
but the innermost level (e.g. the Element Status Descriptor) is
output in hex. Also active with the Additional Element Status
and Threshold In pages. Can be used with an indexing option
and/or --join options.
-j, --join
group elements from the Element Descriptor, Enclosure Status and
Additional Element Status pages. If this option is given twice
then elements from the Threshold In page are also grouped. The
order is dictated by the Configuration page. All elements are
output unless one of the indexing options is given, in which
case only the matching element and its associateds are output.
The --filter option can be added to reduce the amount of output
generated by this option. See the INDEXES and DESCRIPTOR NAME,
DEVICE SLOT NAME AND SAS ADDRESS sections below.
-l, --list
This option is equivalent to --enumerate. See that option.
-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 page abbreviation or code (a number). If PG starts
with a digit it is assumed to be in decimal unless prefixed by
0x for hex. Valid range is 0 to 255 (0x0 to 0xff) inclusive.
Default is page 'sdp' which is page_code 0 (i.e. "Supported
Diagnostic Pages") if no other options are given.
-r, --raw
outputs the chosen status page in ASCII hex in a format suitable
for a later invocation using the --data= option. A page less its
first 4 bytes (page code and length) is output. When used twice
(e.g. -rr) the full page contents is output in binary to stdout.
-A, --sas-addr=SA
where SA is a SAS address found in the Additional Element Status
page. Only entries for SAS devices (with device slot or array
device slot elements) have SAS addresses. 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 DESCRIP‐
TOR NAME, DEVICE SLOT NAME AND SAS ADDRESS section below.
-S, --set=STR
Used to set an element field in the Enclosure Control or Thresh‐
old Out page. Must be used together with an indexing option to
specify which element is to be changed. The Enclosure Control
page is assumed if the --page=PG option is not given. See the
STR FORMAT section below.
-s, --status
will fetch page from the DEVICE via a SCSI RECEIVE DIAGNOSTIC
RESULTS command. In the absence of other options that imply mod‐
ifying a page (e.g. --control or --set=STR) then --status is
assumed.
-v, --verbose
increase the level of verbosity, (i.e. debug output).
-V, --version
print the version string and then exit.
INDEXES
An enclosure can have information about its disk and tape drives plus
other supporting components like power supplies spread across several
pages. Addressing a specific element (overall or individual) within a
page is complicated. This section describes low level indexing (i.e.
choosing a single element (or a group of related elements) from a large
number of elements). If available, the medium level indexing described
in the following section (DESCRIPTOR NAME, DEVICE SLOT NAME AND SAS
ADDRESS) might be simpler to use.
The Configuration page is key to low level indexing: it contains a list
of "type headers", each of which contains an Element type (e.g. Array
Device Slot), a Subenclosure identifier (0 for the primary enclosure)
and a "Number of possible elements". Corresponding to each type header,
the Enclosure Status page has one "overall" element plus "Number of
possible elements" individual elements all of which have the given Ele‐
ment type. For some Element types the "Number of possible elements"
will be 0 so the Enclosure Status page has only one "overall" element
corresponding to that type header. The Element Descriptor page and the
Threshold (In and Out) pages follow the same pattern as the Enclosure
Status page.
The Additional Element Status page is a bit more complicated. It has
entries for "Number of possible elements" of certain Element types. It
does not have entries corresponding to the "overall" elements. To make
the correspondence a little clearer each descriptor in this page
optionally contains an "Element Index Present" (EIP) indicator. If EIP
is set then each element's "Element Index" field refers to the position
of the corresponding element in the Enclosure Status page.
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.
To cope with vendor specific Element types (which should be in the
range 128 to 255) the Element type can be given as a number with a
leading underscore. For example these are equivalent: --index=arr and
--index=_23 since the Array Device Slot Element type value is 23. Also
--index=ps1 and --index=_2_1 are equivalent.
Another example: if the first type header in the Configuration page 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 NAME AND SAS ADDRESS
The three options: --descriptor=DN, --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 invo‐
cation. Each of the three options implicitly set the --join option
since they need either the Element Descriptor page or the Additional
Element Status page as well as the pages 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=DN needs the
Element Descriptor page provided by the SES device however that is
optional. Also the provided descriptor names need to be useful, and
having descriptor names which are all "0" is not very useful. Also some
elements (e.g. overall elements) may not have descriptor names.
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 sugnificant 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 .
The supported list of <acronym>s can be viewed by using the --enumerate
option twice (or "-ee").
CHANGING STATE
This utility has various techniques for changing the state of a SES
device. As noted above this is typically a read-modify-write type
operation. Most modifiable pages have a "status" (or "in") page that
can be read, and a corresponding "control" (or "out") page that can be
written back to change the state of the enclosure.
The lower level technique provided by this utility involves outputting
a "status" page 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 page 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 page (and the Threshold Out page) can
be done at a higher level. This involves choosing a page (the default
in this case is the Enclosure Control page). Next choose an individual
or overall element index (or name it with its Element Descriptor
string). Then give the element's name (e.g. "ident" for RQST IDENT) or
its position within that element (e.g. in an Array Device Slot Control
element RQST IDENT is byte 2, bit 1 and 1 bit long ("2:1:1")). Finally
a value can be given, if not the value for --set=STR defaults to 1 and
for --clear=STR defaults to 0.
SETTING SUBENCLOSURE NICKNAME
The format of the Subenclosure Nickname control page is different from
its corresponding status page. The status page reports all Subenclosure
Nicknames (and Subenclosure identifier 0 is the main enclosure) while
the control page allows only one of them to be changed. Therefore using
the --data option technique to change a Subenclosure nickname is diffi‐
cult (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 page
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 page.
There is an example of changing a nickname in the EXAMPLES section
below.
NOTES
This utility can be used to fetch arbitrary (i.e. non SES) diagnostic
pages (using the SCSI READ DIAGNOSTIC command). To this end the
--page=PG and --hex options would be appropriate. Arbitrary diagnostic
pages 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 with its "element index"
field. The code in this utility interprets the "element index" field as
per the SES-2 standard and if that yields an inappropriate Element
type, adjusts its indexing to follow that vendor's misinterpretation.
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 safte-monitor on the Internet.
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 pages:
sg_ses /dev/bsg/6:0:2:0
To view the Configuration Diagnostic page:
sg_ses --page=cf /dev/bsg/6:0:2:0
To view the Enclosure Status page:
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 page (page 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 pages 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
pages can be changed with the --clear=STR and --set=STR options. [All
modifiable pages 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 page shows that "ArrayDevice07" is
the descriptor name associated with element index 7 then this invoca‐
tion 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 page. The String (In and Out) diagnos‐
tics page is relatively simple (compared with the Enclosure Status/Con‐
trol page). However the use of this lower level technique is awkward
involving three steps: read, modify then write. First check the current
String (In) page contents:
sg_ses --page=str /dev/bsg/6:0:2:0
Now the "read" step. The following command will send the contents of
the String page (from byte 4 onwards) to stdout. The output will be in
ASCII hex with pairs of hex digits representing a byte, 16 pairs per
line, space separated. The redirection puts stdout in a file called
"t":
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 page 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
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 © 2004-2014 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, sg3_utils (in sg3_utils package);
safte-monitor (Internet)
sg3_utils-1.38 January 2014 SG_SES(8)
[top]
List of man pages available for Alpinelinux
Copyright (c) for man pages and the logo by the respective OS vendor.
For those who want to learn more, the polarhome community provides shell access and support.
[legal]
[privacy]
[GNU]
[policy]
[cookies]
[netiquette]
[sponsors]
[FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
|
|
Vote for polarhome
|
