{ "mode": "man", "parameter": "SG_SES", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/SG_SES/8/json", "generated": "2026-10-06T12:05:36Z", "synopsis": "sgses [--all] [--descriptor=DES] [--dev-slot-num=SN] [--eiioe=AF] [--filter] [--get=STR]\n[--hex] [--index=IIA | --index=TIA,II] [--inner-hex] [--join] [--maxlen=LEN] [--page=PG]\n[--quiet] [--raw] [--readonly] [--sas-addr=SA] [--status] [--verbose] [--warn] DEVICE\nsgses --control [--byte1=B1] [--clear=STR] [--data=H,H...] [--data=@FN] [--descriptor=DES]\n[--dev-slot-num=SN] [--index=IIA | --index=TIA,II] [--mask] [--maxlen=LEN] [--nickname=SEN]\n[--nickid=SEID] [--page=PG] [--readonly] [--sas-addr=SA] [--set=STR] [--verbose] DEVICE\nsgses --data=@FN --status [--raw --raw] []\nsgses --inhex=FN --status [--raw --raw] []\nsgses [--enumerate] [--index=IIA] [--list] [--help] [--version]", "sections": { "NAME": { "content": "sgses - access a SCSI Enclosure Services (SES) device\n", "subsections": [] }, "SYNOPSIS": { "content": "sgses [--all] [--descriptor=DES] [--dev-slot-num=SN] [--eiioe=AF] [--filter] [--get=STR]\n[--hex] [--index=IIA | --index=TIA,II] [--inner-hex] [--join] [--maxlen=LEN] [--page=PG]\n[--quiet] [--raw] [--readonly] [--sas-addr=SA] [--status] [--verbose] [--warn] DEVICE\n\nsgses --control [--byte1=B1] [--clear=STR] [--data=H,H...] [--data=@FN] [--descriptor=DES]\n[--dev-slot-num=SN] [--index=IIA | --index=TIA,II] [--mask] [--maxlen=LEN] [--nickname=SEN]\n[--nickid=SEID] [--page=PG] [--readonly] [--sas-addr=SA] [--set=STR] [--verbose] DEVICE\n\nsgses --data=@FN --status [--raw --raw] []\nsgses --inhex=FN --status [--raw --raw] []\n\nsgses [--enumerate] [--index=IIA] [--list] [--help] [--version]\n", "subsections": [] }, "DESCRIPTION": { "content": "Fetches management information from a SCSI Enclosure Service (SES) device. This utility can\nalso modify the state of a SES device. The DEVICE should be a SES device which may be a dedi‐\ncated enclosure services processor in which case an INQUIRY response's Peripheral Device Type\nis 13 [0xd]. Alternatively it may be attached to another type of SCSI device (e.g. a disk) in\nwhich case the EncServ bit is set in its INQUIRY response.\n\nIf the DEVICE argument is given with no options then the names of all diagnostic pages\n(dpages) supported are listed. Most, but not necessarily all, of the named dpages are defined\nin the SES standards and drafts. The most recent reference for this utility is the draft SCSI\nEnclosure Services 4 document T10/BSR INCITS 555 Revision 5 at http://www.t10.org . Existing\nstandards for SES, SES-2 and SES-3 are ANSI INCITS 305-1998 and ANSI INCITS 448-2008 and ANSI\nINCITS 518-2017 respectively.\n\nThe first form shown in the synopsis is for fetching and decoding dpages or fields from the\nSES DEVICE. A SCSI RECEIVE DIAGNOSTIC RESULTS command is sent to the DEVICE to obtain each\ndpage response. Rather than decoding a fetched dpage, it may be output in hex or binary with\nthe --hex or --raw --raw options.\n\nThe second form in the synopsis is for modifying dpages or fields held in the SES DEVICE. A\nSCSI SEND DIAGNOSTIC command containing a \"control\" dpage is sent to the DEVICE to cause\nchanges. Changing the state of an enclosure (e.g. requesting the \"ident\" (locate) LED to\nflash on a disk carrier in an array) is typically done using a read-modify-write cycle. See\nthe section on CHANGING STATE below.\n\nThe third form in the synopsis has two equivalent invocations shown. They decode the contents\nof a file (named FN) that holds a hexadecimal or binary representation of one, or many, SES\ndpage responses. Typically an earlier invocation of the first form of this utility with the\n'-HHHH' option would have generated that file. Since no SCSI commands are sent, the DEVICE\nargument if given will be ignored.\n\nThe last form in the synopsis shows the options for providing command line help (i.e. usage\ninformation), listing out dpage and field information tables held by the utility (--enumer‐\nate), or printing the version string of this utility.\n\nThere is a web page discussing this utility at http://sg.danny.cz/sg/sgses.html . Support\nfor downloading microcode to a SES device has been placed in a separate utility called\nsgsesmicrocode.\n\nIn the following sections \"dpage\" refers to a diagnostic page, either fetched with a SCSI RE‐\nCEIVE DIAGNOSTIC RESULTS command, sent to the DEVICE with a SCSI SEND DIAGNOSTIC command, or\nfetched from data supplied by the --data= option.\n", "subsections": [] }, "OPTIONS": { "content": "Arguments to long options are mandatory for short options as well. The options are arranged\nin alphabetical order based on the long option name.\n", "subsections": [ { "name": "-a --all", "content": "shows (almost) all status dpages, following references and presenting the information\nas a long list whose indentation indicates the level of nesting. This option is actu‐\nally the same as --join, see its description for more information.\n", "flag": "-a", "long": "--all" }, { "name": "-b --byte1", "content": "some modifiable dpages may need byte 1 (i.e. the second byte) set. In the Enclosure\nControl dpage, byte 1 contains the INFO, NON-CRIT, CRIT and UNRECOV bits. In the\nSubenclosure String Out, Subenclosure Nickname Control and Download Microcode Control\ndpages, byte 1 is the Subenclosure identifier. Active when the --control and\n--data=H,H... options are used and the default value is 0. If the --clear=STR or\n--set=STR option is used then the value read from byte 1 is written back to byte 1.\nB1 is in decimal unless it is prefixed by '0x' or '0X' (or has a trailing 'h' or 'H').\n", "flag": "-b", "long": "--byte1" }, { "name": "-C --clear", "content": "Used to clear an element field in the Enclosure Control or Threshold Out dpage. Must\nbe used together with an indexing option to specify which element is to be changed.\nThe Enclosure Control dpage is assumed if the --page=PG option is not given. See the\nSTR FORMAT and the CLEAR, GET, SET sections below.\n", "flag": "-C", "long": "--clear" }, { "name": "-c --control", "content": "will send control information to the DEVICE via a SCSI SEND DIAGNOSTIC command. Cannot\ngive both this option and --status. The Enclosure Control, String Out, Threshold Out,\nArray Control (obsolete in SES-2), Subenclosure String Out, Subenclosure Nickname Con‐\ntrol and Download Microcode dpages can be set currently. This option is assumed if ei‐\nther the --clear=STR or --set=STR option is given.\n", "flag": "-c", "long": "--control" }, { "name": "-d --data", "content": "permits a string of comma separated (ASCII) hex bytes to be specified (limit 1024). A\n(single) space separated string of hex bytes is also allowed but the list needs to be\nin quotes. This option allows the parameters to a control dpage to be specified. The\nstring given should not include the first 4 bytes (i.e. page code and length). See the\nDATA SUPPLIED section below.\n", "flag": "-d", "long": "--data" }, { "name": "-d --data", "content": "reads one or more data strings from stdin, limit almost 216 bytes. stdin may provide\nASCII hex as a comma separated list (i.e. as with the --data=H,H... option). Addition‐\nally spaces, tabs and line feeds are permitted as separators from stdin . Stops read‐\ning stdin when an EOF is detected. See the DATA SUPPLIED section below.\n", "flag": "-d", "long": "--data" }, { "name": "-d --data", "content": "reads one or more data strings from the file called FN, limit almost 216 bytes. The\ncontents of the file is decoded in the same fashion as stdin described in the previous\noption. See the DATA SUPPLIED section below.\n", "flag": "-d", "long": "--data" }, { "name": "-D --descriptor", "content": "where DES is a descriptor name (string) as found in the Element Descriptor dpage. This\nis a medium level indexing alternative to the low level --index= options. If the de‐\nscriptor name contains a space then DES needs to be surrounded by quotes (single or\ndouble) or the space escaped (e.g. preceded by a backslash). See the DESCRIPTOR NAME,\nDEVICE SLOT NUMBER AND SAS ADDRESS section below.\n", "flag": "-D", "long": "--descriptor" }, { "name": "-x --dev-slot-num --dsn", "content": "where SN is a device slot number found in the Additional Element Status dpage. Only\nentries for FCP and SAS devices (with EIP=1) have device slot numbers. SN must be a\nnumber in the range 0 to 255 (inclusive). 255 is used to indicate there is no corre‐\nsponding device slot. This is a medium level indexing alternative to the low level\n--index= options. See the DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS section\nbelow.\n", "flag": "-x", "long": "--dsn" }, { "name": "-E --eiioe", "content": "AF is either the string 'auto' or 'force'. There was some fuzziness in the interpre‐\ntation of the 'element index' field in the Additional Element Status (AES) dpage be‐\ntween SES-2 and SES-3. The EIIOE bit was introduced to resolve the problem but not all\nenclosures have caught up. In the SES-3 revision 12 draft the EIIOE bit was expanded\nto a 2 bit EIIOE field. Using '--eiioe=force' will decode the AES dpage as if the EI‐\nIOE field is set to 1. Using '--eiioe=auto' will decode the AES dpage as if the EIIOE\nfield is set to 1 if the first AES descriptor has its EIP bit set and its element in‐\ndex field is 1 (in other words a heuristic to guess whether the EIIOE field should be\nset to 1 or 0).\nIf the enclosure sets the actual EIIOE field to 1 or more then this option has no ef‐\nfect. It is recommended that HP JBOD users set --eiioe=auto .\n", "flag": "-E", "long": "--eiioe" }, { "name": "-e --enumerate", "content": "enumerate all known diagnostic page (dpage) names and SES elements that this utility\nrecognizes plus the abbreviations accepted by this utility. Ignores DEVICE if it is\ngiven. Essentially it is dumping out tables held internally by this utility.\nIf --enumerate is given twice, then the recognised acronyms for the --clear=STR,\n--get=STR and --set=STR options are listed. The utility exits after listing this in‐\nformation, so most other options and DEVICE are ignored. Since there are many acronyms\nfor the Enclosure Control/Status dpage then the output can be further restricted by\ngiving the --index=IIA option (e.g. \"sgses -ee -I ts\" to only show the acronyms asso‐\nciated with the Enclosure Control/Status dpage's Temperature Sensor Element Type).\n", "flag": "-e", "long": "--enumerate" }, { "name": "-f --filter", "content": "cuts down on the amount of output from the Enclosure Status dpage and the Additional\nElement Status dpage. When this option is given, any line which has all its binary\nflags cleared (i.e. 0) is filtered out (i.e. ignored). If a line has some other\nvalue on it (e.g. a temperature) then it is output. When this option is used twice\nonly elements associated with the \"status=ok\" field (in the Enclosure status dpage)\nare output. The --filter option is useful for reducing the amount of output generated\nby the --join option.\n", "flag": "-f", "long": "--filter" }, { "name": "-G --get", "content": "Used to read a field in a status element. Must be used together with a an indexing op‐\ntion to specify which element is to be read. By default the Enclosure Status dpage is\nread, the only other dpages that can be read are the Threshold In and Additional Ele‐\nment Status dpages. If a value is found it is output in decimal to stdout (by default)\nor in hexadecimal preceded by \"0x\" if the --hex option is also given. See the STR FOR‐\nMAT and the CLEAR, GET, SET sections below.\n", "flag": "-G", "long": "--get" }, { "name": "-h --help", "content": "output the usage message then exit. Since there is a lot of information, it is split\ninto two pages. The most important is shown on the first page. Use this option twice\n(e.g. '-hh') to output the second page. Note: the --enumerate option might also be\nviewed as a help or usage type option. And like this option it has a \"given twice\"\nform: '-ee'.\n", "flag": "-h", "long": "--help" }, { "name": "-H --hex", "content": "If the --get=STR option is given then output the value found (if any) in hexadecimal,\nwith a leading \"0x\". Otherwise output the response in hexadecimal; with trailing ASCII\nif given once, without it if given twice, and simple hex if given three or more times.\nIgnored when all elements from several dpages are being accessed (e.g. when the --join\noption is used). Also see the --raw option which may be used with this option.\nTo dump one of more dpage responses to stdout in ASCII parsable hexadecimal use -HHH\nor -HHHH. The triple H form only outputs hexadecimals which is fine for a single dpage\nresponse. When all dpages are dumped (e.g. with --page=all) then the quad H form adds\nthe name of each dpage following a hash mark ('#'). The --data= option parser ignores\neverything from and including a hash mark to the end of the line. Hence the output of\nthe quad H form is still parsable plus it is easier for users to view and possibly\nedit. -HHHHH (that is 5) adds the page code in hex after the page's name in the com‐\nment.\n", "flag": "-H", "long": "--hex" }, { "name": "-I --index", "content": "where IIA is either an individual index (II) or an Element type abbreviation (A). See\nthe INDEXES section below. If the --page=PG option is not given then the Enclosure\nStatus (or Control) dpage is assumed. May be used with the --join option or one of\nthe --clear=STR, --get=STR or --set=STR options. To enumerate the available Element\ntype abbreviations use the --enumerate option.\n", "flag": "-I", "long": "--index" }, { "name": "-I --index", "content": "where TIA,II is an type header index (TI) or Element type abbreviation (A) followed by\nan individual index (II). See the INDEXES section below. If the --page=PG option is\nnot given then the Enclosure Status (or Control) dpage is assumed. May be used with\nthe --join option or one of the --clear=STR, --get=STR or --set=STR options. To enu‐\nmerate the available Element type abbreviations use the --enumerate option.\n", "flag": "-I", "long": "--index" }, { "name": "-X --inhex", "content": "where FN is a filename. It has the equivalent action of the --data=@FN option. If FN\nis '-' then stdin is read. This option has been given for compatibility with other\nutilities in this package that use --inhex=FN (or --in=FN) is a similar way. See the\n\"FORMAT OF FILES CONTAINING ASCII HEX\" section in the sg3utils manpage for more in‐\nformation.\n", "flag": "-X", "long": "--inhex" }, { "name": "-i --inner-hex", "content": "the outer levels of a status dpage are decoded and printed out but the innermost level\n(e.g. the Element Status Descriptor) is output in hex. Also active with the Additional\nElement Status and Threshold In dpages. Can be used with an indexing option and/or\n--join options.\n", "flag": "-i", "long": "--inner-hex" }, { "name": "-j --join", "content": "group elements from the Element Descriptor, Enclosure Status and Additional Element\nStatus dpages. If this option is given twice then elements from the Threshold In dpage\nare also grouped. The order is dictated by the Configuration dpage.\nThere can be a bewildering amount of information in the \"join\" output. The default is\nto output everything. Several additional options are provided to cut down the amount\ndisplayed. If the indexing options is given, only the matching elements and their as‐\nsociated fields are output. The --filter option (see its description) can be added to\nreduce the amount of output. Also \"--page=aes\" (or \"-p 0xa\") can be added to suppress\nthe output of rows that don't have a \"aes\" dpage component. See the INDEXES and DE‐\nSCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS sections below.\n", "flag": "-j", "long": "--join" }, { "name": "-l --list", "content": "This option is equivalent to --enumerate. See that option.\n", "flag": "-l", "long": "--list" }, { "name": "-M --mask", "content": "When modifying elements, the default action is a read (status element), mask, modify\n(based on --clear=STR or --set=STR) then write back as the control element. The mask\nstep is new in sgses version 1.98 and is based on what is allowable (and in the same\nlocation) in draft SES-3 revision 6. Those masks may evolve, as they have in the past.\nThis option re-instates the previous logic which was to ignore the mask step. The de‐\nfault action (i.e. without this option) is to perform the mask step in the\nread-mask-modify-write sequence.\n", "flag": "-M", "long": "--mask" }, { "name": "-m --maxlen", "content": "LEN is placed in the ALLOCATION LENGTH field of the SCSI RECEIVE DIAGNOSTIC RESULTS\ncommands sent by the utility. It represents the maximum size of data the SES device\ncan return (in bytes). It cannot exceed 65535 and defaults to 65532 (bytes). Some sys‐\ntems may not permit such large sizes hence the need for this option. If LEN is less\nthan 0 or greater than 65535 then an error is generated. If LEN is 0 then the default\nvalue is used, otherwise if it is less than 4 then it is ignored (and a warning is\nsent to stderr).\n", "flag": "-m", "long": "--maxlen" }, { "name": "-n --nickname", "content": "where SEN is the new Subenclosure Nickname. Only the first 32 characters (bytes) of\nSEN are used, if more are given they are ignored. See the SETTING SUBENCLOSURE NICK‐\nNAME section below.\n", "flag": "-n", "long": "--nickname" }, { "name": "-N --nickid", "content": "where SEID is the Subenclosure identifier that the new Nickname (SEN) will be applied\nto. So SEID must be an existing Subenclosure identifier. The default value is 0 which\nis the main enclosure.\n", "flag": "-N", "long": "--nickid" }, { "name": "-p --page", "content": "where PG is a dpage abbreviation or code (a number). If PG starts with a digit it is\nassumed to be in decimal unless prefixed by 0x for hex. Valid range is 0 to 255 (0x0\nto 0xff) inclusive. Default is dpage 'sdp' which is pagecode 0 (i.e. \"Supported Diag‐\nnostic Pages\") if no other options are given.\nPage code 0xff or abbreviation \"all\" is not a real dpage (as the highest real dpage is\n0x3f) but instead causes all dpages whose page code is 0x2f or less to be output. This\ncan be used with either the -HHHH or -rr to send either hexadecimal ASCII or binary\nrespectively to stdout.\nTo list the available dpage abbreviations give \"xxx\" for PG; the same information can\nalso be found with the --enumerate option.\n", "flag": "-p", "long": "--page" }, { "name": "-q --quiet", "content": "this suppresses the number of warnings and messages output. The exit status of the\nutility is unaffected by this option.\n", "flag": "-q", "long": "--quiet" }, { "name": "-r --raw", "content": "outputs the chosen status dpage in ASCII hex in a format suitable for a later invoca‐\ntion using the --data= option. A dpage less its first 4 bytes (page code and length)\nis output. When used twice (e.g. -rr) the full dpage contents is output in binary to\nstdout.\nwhen -rr is used together with the --data=- or --data=@FN then stdin or file FN is de‐\ncoded as a binary stream that continues to be read until an end of file (EOF). Once\nthat data is read then the internal raw option is cleared to 0 so the output is not\neffected. So the -rr option either changes how the input or output is treated, but not\nboth.\n", "flag": "-r", "long": "--raw" }, { "name": "-R --readonly", "content": "open the DEVICE read-only (e.g. in Unix with the ORDONLY flag). The default is to\nopen it read-write.\n", "flag": "-R", "long": "--readonly" }, { "name": "-A --sas-addr", "content": "this is an indexing method for SAS end devices (e.g. SAS disks). The utility will try\nto find the element or slot in the Additional Element Status dpage whose SAS address\nmatches SA. For a SAS disk or tape that SAS address is its target port identifier for\nthe port connected to that element or slot. Most SAS disks and tapes have two such\ntarget ports, usually numbered consecutively.\nSATA devices in a SAS enclosure often receive \"manufactured\" target port identifiers\nfrom a SAS expander; typically will have a SAS address close to, but different from,\nthe SAS address of the expander itself. Note that this manufactured target port iden‐\ntifier is different from a SATA disk's WWN.\nSA is a hex number that is up to 8 digits long. It may have a leading '0x' or '0X' or\na trailing 'h' or 'H'. This option is a medium level\nindexing alternative to the low level --index= options. See the DESCRIPTOR NAME, DE‐\nVICE SLOT NUMBER AND SAS ADDRESS section below.\n", "flag": "-A", "long": "--sas-addr" }, { "name": "-S --set", "content": "Used to set an element field in the Enclosure Control or Threshold Out dpage. Must be\nused together with an indexing option to specify which element is to be changed. The\nEnclosure Control dpage is assumed if the --page=PG option is not given. See the STR\nFORMAT and CLEAR, GET, SET sections below.\n", "flag": "-S", "long": "--set" }, { "name": "-s --status", "content": "will fetch dpage from the DEVICE via a SCSI RECEIVE DIAGNOSTIC RESULTS command (or\nfrom --data=@FN). In the absence of other options that imply modifying a dpage (e.g.\n--control or --set=STR) then --status is assumed, except when the --data= option is\ngiven. When the --data= option is given there is no default action: either the --con‐\ntrol or this option must be given to distinguish between the two different ways that\ndata will be treated.\n", "flag": "-s", "long": "--status" }, { "name": "-v --verbose", "content": "increase the level of verbosity. For example when this option is given four times (in\nwhich case the short form is more convenient: '-vvvv') then if the internal join array\nhas been generated then it is output to stderr in a form suitable for debugging.\n", "flag": "-v", "long": "--verbose" }, { "name": "-V --version", "content": "print the version string and then exit.\n", "flag": "-V", "long": "--version" }, { "name": "-w --warn", "content": "warn about certain irregularities with warnings sent to stderr. The join is a complex\noperation that relies on information from several dpages to be synchronized. The qual‐\nity of SES devices vary and to be fair, the descriptions from T10 drafts and standards\nhave been tweaked several times (see the EIIOE field) in order to clear up confusion.\n", "flag": "-w", "long": "--warn" } ] }, "INDEXES": { "content": "An enclosure can have information about its disk and tape drives plus other supporting compo‐\nnents like power supplies spread across several dpages. Addressing a specific element (over‐\nall or individual) within a dpage is complicated. This section describes low level indexing\n(i.e. choosing a single element (or a group of related elements) from a large number of ele‐\nments). If available, the medium level indexing described in the following section (DESCRIP‐\nTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS) might be simpler to use.\n\nThe Configuration dpage is key to low level indexing: it contains a list of \"type headers\",\neach of which contains an Element type (e.g. Array Device Slot), a Subenclosure identifier (0\nfor the primary enclosure) and a \"Number of possible elements\". Corresponding to each type\nheader, the Enclosure Status dpage has one \"overall\" element plus \"Number of possible ele‐\nments\" individual elements all of which have the given Element type. For some Element types\nthe \"Number of possible elements\" will be 0 so the Enclosure Status dpage has only one \"over‐\nall\" element corresponding to that type header. The Element Descriptor dpage and the Thresh‐\nold (In and Out) dpages follow the same pattern as the Enclosure Status dpage.\n\nThe numeric index corresponding to the overall element is \"-1\". If the Configuration dpage\nindicates a particular element type has \"n\" elements and n is greater than 0 then its indexes\nrange from 0 to n-1 .\n\nThe Additional Element Status dpage is a bit more complicated. It has entries for \"Number of\npossible elements\" of certain Element types. It does not have entries corresponding to the\n\"overall\" elements. To make the correspondence a little clearer each descriptor in this dpage\noptionally contains an \"Element Index Present\" (EIP) indicator. If EIP is set then each ele‐\nment's \"Element Index\" field refers to the position of the corresponding element in the En‐\nclosure Status dpage.\n\nAddressing a single overall element or a single individual element is done with two indexes:\nTI and II. Both are origin 0. TI=0 corresponds to the first type header entry which must be a\nDevice Slot or Array Device Slot Element type (according to the SES-2 standard). To address\nthe corresponding overall instance, II is set to -1, otherwise II can be set to the individ‐\nual instance index. As an alternative to the type header index (TI), an Element type abbrevi‐\nation (A) optionally followed by a number (e.g. \"ps\" refers to the first Power Supply Element\ntype; \"ps1\" refers to the second) can be given.\n\nOne of two command lines variants can be used to specify indexes: --index=TIA,II where TIA is\neither an type header index (TI) or an Element type abbreviation (A) (e.g. \"ps\" or \"ps1\"). II\nis either an individual index or \"-1\" to specify the overall element. The second variant is\n--index=IIA where IIA is either an individual index (II) or an Element type abbreviation (A).\nWhen IIA is an individual index then the option is equivalent to --index=0,II. When IIA is an\nElement type abbreviation then the option is equivalent to --index=A,-1.\n\nWherever an individual index is applicable, it can be replaced by an individual index range.\nIt has the form: -. For example: '3-5' will select individual indexes 3, 4\nand 5 .\n\nTo cope with vendor specific Element types (whose type codes should be in the range 128 to\n255) the Element type code can be given as a number with a leading underscore. For example\nthese are equivalent: --index=arr and --index=23 since the Array Device Slot Element type\ncode is 23. Also --index=ps1 and --index=21 are equivalent.\n\nAnother example: if the first type header in the Configuration dpage has has Array Device\nSlot Element type then --index=0,-1 is equivalent to --index=arr. Also --index=arr,3 is\nequivalent to --index=3.\n\nThe --index= options can be used to reduce the amount of output (e.g. only showing the ele‐\nment associated with the second 12 volt power supply). They may also be used together with\nwith the --clear=STR, --get=STR and --set=STR options which are described in the STR section\nbelow.\n\nDESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS\nThe three options: --descriptor=DES, --dev-slot-num=SN and --sas-addr=SA allow medium level\nindexing, as an alternative to the low level --index= options. Only one of the three options\ncan be used in an invocation. Each of the three options implicitly set the --join option\nsince they need either the Element Descriptor dpage or the Additional Element Status dpage as\nwell as the dpages needed by the --index= option.\n\nThese medium level indexing options need support from the SES device and that support is op‐\ntional. For example the --descriptor=DES needs the Element Descriptor dpage provided by the\nSES device however that is optional. Also the provided descriptor names need to be useful,\nand having descriptor names which are all \"0\" is not very useful. Also some elements (e.g.\noverall elements) may not have descriptor names.\n\nThese medium level indexing options can be used to reduce the amount of output (e.g. only\nshowing the elements related to device slot number 3). They may also be used together with\nwith the --clear=STR, --get=STR and --set=STR options which are described in the following\nsection. Note that even if a field can be set (e.g. \"do not remove\" (dnr)) and that field can\nbe read back with --get=STR confirming that change, the disk array may still ignore it (e.g.\nbecause it does not have the mechanism to lock the disk drawer).\n", "subsections": [] }, "STR FORMAT": { "content": "The STR operands of the --clear=STR, --get=STR and --set=STR options all have the same struc‐\nture. There are two forms:\n[=]\n:[:][=]\n\nThe is one of a list of common fields (e.g. \"ident\" and \"fault\") that the utility\nconverts internally into the second form. The is usually in the range 0 to 3,\nthe must be in the range 0 to 7 and the must be in the range 1 to 64\n(default 1). The number of bits are read in the left to right sense of the element tables\nshown in the various SES draft documents. For example the 8 bits of byte 2 would be repre‐\nsented as 2:7:8 with the most significant bit being 2:7 and the least significant bit being\n2:0 .\n\nThe is optional but is ignored if provided to --get=STR. For --set=STR the default\n is 1 while for --clear=STR the default value is 0 . is assumed to be decimal,\nhexadecimal values can be given in the normal fashion.\n\nThe supported list of s can be viewed by using the --enumerate option twice (or\n\"-ee\").\n\nCLEAR, GET, SET\nThe --clear=STR, --get=STR and --set=STR options can be used up to 8 times in the same invo‐\ncation. Any s used in the STR operands must refer to the same dpage.\n\nWhen multiple of these options are used (maximum: 8), they are applied in the order in which\nthey appear on the command line. So if options contradict each other, the last one appearing\non the command line will be enforced. When there are multiple --clear=STR and --set=STR op‐\ntions, then the dpage they refer to is only written after the last one.\n", "subsections": [] }, "DATA SUPPLIED": { "content": "This section describes the two scenarios that can occur when the --data= option is given.\nThese scenarios are the same irrespective of whether the argument to the --data= option is a\nstring of hex bytes on the command line, stdin (indicated by --data=-) or names a file (e.g.\n--data=@threshindpage.hex).\n\nThe first scenario is flagged by the --control option. It uses the supplied data to build a\n'control' dpage that will be sent to the DEVICE using the SCSI SCSI SEND DIAGNOSTIC command.\nThe supplied dpage data should not include its first 4 bytes. Those 4 bytes are added by this\nutility using the --page=PG option with PG placed at byte offset 0). If needed, the\n--byte1=B1 option sets byte offset 1, else 0 is placed in that position. The number of bytes\ndecoded from the data provided (i.e. its length) goes into byte offsets 2 and 3.\n\nThe second scenario is flagged by the --status option. It decodes the supplied data assuming\nthat it represents the response to one or more SCSI RECEIVE DIAGNOSTIC RESULTS commands.\nThose responses have typically been captured from some earlier invocation(s) of this utility.\nThose earlier invocations could use the '-HHH' or '-HHHH' option and file redirection to cap‐\nture that response (or responses) in hexadecimal. The supplied dpage response data is decoded\naccording to the other command line options. For example the --join option could be given and\nthat would require the data from multiple dpages typically: Configuration, Enclosure status,\nElement descriptor and Additional element status dpages. If in doubt use --page=all in the\ncapture phase; having more dpages than needed is not a problem.\n\nBy default the user supplied data is assumed to be ASCII hexadecimal in lines that don't ex‐\nceed 512 characters. Anything on a line from and including a hash mark ('#') to the end of\nline is ignored. An end of line can be a LF or CR,LF and blank lines are ignored. Each sepa‐\nrated pair (or single) hexadecimal digits represent a byte (and neither a leading '0x' nor a\ntrailing 'h' should be given). Separators are either space, tab, comma or end of line.\n\nAlternatively binary can be used and this is flagged by the '-rr' option. The --data=H,H...\nform cannot use binary values for the 'H's, only ASCII hexadecimal. The other two forms\n(--data=- and --data=@FN) may contain binary data. Note that when the '-rr' option is used\nwith --data=@FN that it only changes the interpretation of the input data, it does not change\nthe decoding and output representation.\n", "subsections": [] }, "CHANGING STATE": { "content": "This utility has various techniques for changing the state of a SES device. As noted above\nthis is typically a read-modify-write type operation. Most modifiable dpages have a \"status\"\n(or \"in\") page that can be read, and a corresponding \"control\" (or \"out\") dpage that can be\nwritten back to change the state of the enclosure.\n\nThe lower level technique provided by this utility involves outputting a \"status\" dpage in\nhex with --raw. Then a text editor can be used to edit the hex (note: to change an Enclosure\nControl descriptor the SELECT bit needs to be set). Next the control dpage data can fed back\nwith the --data=H,H... option together with the --control option; the --byte1=B1 option may\nneed to be given as well.\n\nChanges to the Enclosure Control dpage (and the Threshold Out dpage) can be done at a higher\nlevel. This involves choosing a dpage (the default in this case is the Enclosure Control\ndpage). Next choose an individual or overall element index (or name it with its Element De‐\nscriptor string). Then give the element's name (e.g. \"ident\" for RQST IDENT) or its position\nwithin that element (e.g. in an Array Device Slot Control element RQST IDENT is byte 2, bit 1\nand 1 bit long (\"2:1:1\")). Finally a value can be given, if not the value for --set=STR de‐\nfaults to 1 and for --clear=STR defaults to 0.\n", "subsections": [] }, "SETTING SUBENCLOSURE NICKNAME": { "content": "The format of the Subenclosure Nickname control dpage is different from its corresponding\nstatus dpage. The status dpage reports all Subenclosure Nicknames (and Subenclosure identi‐\nfier 0 is the main enclosure) while the control dpage allows only one of them to be changed.\nTherefore using the --data option technique to change a Subenclosure nickname is difficult\n(but still possible).\n\nTo simplify changing a Subenclosure nickname the --nickname=SEN and --nickid=SEID options\nhave been added. If the SEN string contains spaces or other punctuation, it should be quoted:\nsurrounded by single or double quotes (or the offending characters escaped). If the\n--nickid=SEID is not given then a Subenclosure identifier of 0 is assumed. As a guard the\n--control option must also be given. If the --page=PG option is not given then --page=snic is\nassumed.\n\nWhen --nickname=SEN is given then the Subenclosure Nickname Status dpage is read to obtain\nthe Generation Code field. That Generation Code together with no more than 32 bytes from the\nNickname (SEN) and the Subenclosure Identifier (SEID) are written to the Subenclosure Nick‐\nname Control dpage.\n\nThere is an example of changing a nickname in the EXAMPLES section below.\n", "subsections": [] }, "NVME ENCLOSURES": { "content": "Support has been added to sgses (actually, its underlying library) for NVMe (also known as\nNVM Express) Enclosures. It can be considered experimental in sg3utils package version 1.43\nand sgses version 2.34 .\n\nThis support is based on a decision by NVME-MI (Management Interface) developers to support\nthe SES-3 standard. This was facilitated by adding NVME-MI SES Send and SES Receive commands\nthat tunnel dpage contents as used by SES.\n", "subsections": [] }, "NOTES": { "content": "This utility can be used to fetch arbitrary (i.e. non SES) dpages (using the SCSI READ DIAG‐\nNOSTIC command). To this end the --page=PG and --hex options would be appropriate. Non-SES\ndpages can be sent to a device with the sgsenddiag utility.\n\nThe most troublesome part of the join operation is associating Additional Element Status de‐\nscriptors correctly. At least one SES device vendor has misinterpreted the SES-2 standard,\nspecifically with its \"element index\" field interpretation. The code in this utility inter‐\nprets the \"element index\" field as per the SES-2 standard and if that yields an inappropriate\nElement type, adjusts its indexing to follow that vendor's misinterpretation. The SES-3\ndrafts have introduced the EIIOE (Element Index Includes Overall Elements) bit which later\nbecame a 2 bit field to resolve this ambiguity. See the --eiioe=AF option.\n\nIn draft SES-3 revision 5 the \"Door Lock\" element name was changed to the \"Door\" (and an OPEN\nfield was added to the status element). As a consequence the former 'dl' element type abbre‐\nviation has been changed to 'do'.\n\nThere is a related command set called SAF-TE (SCSI attached fault-tolerant enclosure) for en‐\nclosure (including RAID) status and control. SCSI devices that support SAF-TE report \"Proces‐\nsor\" peripheral device type (0x3) in their INQUIRY response. See the sgsafte utility in this\npackage or the safte-monitor utility on the Internet.\n\nThe internal join array is statically allocated and its size is controlled by the\nMXJOINROWS define. Its current value is 520.\n", "subsections": [] }, "EXAMPLES": { "content": "Examples can also be found at http://sg.danny.cz/sg/sgses.html\n\nThe following examples use Linux device names. For suitable device names in other supported\nOperating Systems see the sg3utils(8) man page.\n\nTo view the supported dpages:\n\nsgses /dev/bsg/6:0:2:0\n\nTo view the Configuration Diagnostic dpage:\n\nsgses --page=cf /dev/bsg/6:0:2:0\n\nTo view the Enclosure Status dpage:\n\nsgses --page=es /dev/bsg/6:0:2:0\n\nTo get the (attached) SAS address of that device (which is held in the Additional Element\nSense dpage (dpage 10)) printed on hex:\n\nsgses -p aes -D ArrayDevice07 -G atsasaddr -H /dev/sg3\n\nTo collate the information in the Enclosure Status, Element Descriptor and Additional Element\nStatus dpages the --join option can be used:\n\nsgses --join /dev/sg3\n\nThis will produce a lot of output. To filter out lines that don't contain much information\nadd the --filter option:\n\nsgses --join --filter /dev/sg3\n\nFields in the various elements of the Enclosure Control and Threshold dpages can be changed\nwith the --clear=STR and --set=STR options. [All modifiable dpages can be changed with the\n--raw and --data=H,H... options.] The following example looks at making the \"ident\" LED (also\ncalled \"locate\") flash on \"ArrayDevice07\" which is a disk (or more precisely the carrier\ndrawer the disk is in):\n\nsgses --index=7 --set=2:1:1 /dev/sg3\n\nIf the Element Descriptor diagnostic dpage shows that \"ArrayDevice07\" is the descriptor name\nassociated with element index 7 then this invocation is equivalent to the previous one:\n\nsgses --descriptor=ArrayDevice07 --set=2:1:1 /dev/sg3\n\nFurther the byte 2, bit 1 (for 1 bit) field in the Array Device Slot Control element is RQST\nIDENT for asking a disk carrier to flash a LED so it can be located. In this case \"ident\" (or\n\"locate\") is accepted as an acronym for that field:\n\nsgses --descriptor=ArrayDevice07 --set=ident /dev/sg3\n\nTo stop that LED flashing:\n\nsgses --dev-slot-num=7 --clear=ident /dev/sg3\n\nThe above assumes the descriptor name 'ArrayDevice07' corresponds to device slot number 7.\n\nNow for an example of a more general but lower level technique for changing a modifiable di‐\nagnostic dpage. The String (In and Out) diagnostics dpage is relatively simple (compared with\nthe Enclosure Status/Control dpage). However the use of this lower level technique is awkward\ninvolving three steps: read, modify then write. First check the current String (In) dpage\ncontents:\n\nsgses --page=str /dev/bsg/6:0:2:0\n\nNow the \"read\" step. The following command will send the contents of the String dpage (from\nbyte 4 onwards) to stdout. The output will be in ASCII hex with pairs of hex digits repre‐\nsenting a byte, 16 pairs per line, space separated. The redirection puts stdout in a file\ncalled \"t\":\n\nsgses --page=str --raw /dev/bsg/6:0:2:0 > t\n\nThen with the aid of the SES-3 document (in revision 3: section 6.1.6) use your favourite ed‐\nitor to change t. The changes can be sent to the device with:\n\nsgses --page=str --control --data=- /dev/bsg/6:0:2:0 < t\n\nIf the above is successful, the String dpage should have been changed. To check try:\n\nsgses --page=str /dev/bsg/6:0:2:0\n\nTo change the nickname on the main enclosure:\n\nsgses --nickname='1st enclosure' --control /dev/bsg/6:0:2:0\n\nTo capture the whole state of an enclosure (from a SES perspective) for later analysis, this\ncan be done:\n\nsgses --page=all -HHHH /dev/sg5 > encsg5all.hex\n\nNote that if there are errors or warnings they will be sent to stderr so they will appear on\nthe command line (since only stdout is redirected). A text editor could be used to inspect\nencsg5all.hex . If all looks in order at some later time, potentially on a different ma‐\nchine where encsg5all.hex has been copied, a \"join\" could be done. Note that join reflects\nthe state of the enclosure when the capture was done.\n\nsgses --data=@encsg5all.hex --status --join\n", "subsections": [] }, "EXIT STATUS": { "content": "The exit status of sgses is 0 when it is successful. Otherwise see the sg3utils(8) man\npage.\n", "subsections": [] }, "AUTHORS": { "content": "Written by Douglas Gilbert.\n", "subsections": [] }, "REPORTING BUGS": { "content": "Report bugs to .\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright © 2004-2021 Douglas Gilbert\nThis software is distributed under a FreeBSD license. There is NO warranty; not even for MER‐\nCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n", "subsections": [] }, "SEE ALSO": { "content": "", "subsections": [ { "name": "sg_inq, sg_safte, sg_senddiag, sg_ses_microcode, sg3_utils (sg3_utils); safte-monitor (Inter‐", "content": "" }, { "name": "net)", "content": "sg3utils-1.46 February 2021 SGSES(8)" } ] } }, "summary": "sgses - access a SCSI Enclosure Services (SES) device", "flags": [ { "flag": "-a", "long": "--all", "arg": null, "description": "shows (almost) all status dpages, following references and presenting the information as a long list whose indentation indicates the level of nesting. This option is actu‐ ally the same as --join, see its description for more information." }, { "flag": "-b", "long": "--byte1", "arg": null, "description": "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')." }, { "flag": "-C", "long": "--clear", "arg": null, "description": "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." }, { "flag": "-c", "long": "--control", "arg": null, "description": "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 Nickname Con‐ trol and Download Microcode dpages can be set currently. This option is assumed if ei‐ ther the --clear=STR or --set=STR option is given." }, { "flag": "-d", "long": "--data", "arg": null, "description": "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." }, { "flag": "-d", "long": "--data", "arg": null, "description": "reads one or more data strings from stdin, limit almost 216 bytes. stdin may provide ASCII hex as a comma separated list (i.e. as with the --data=H,H... option). Addition‐ ally spaces, tabs and line feeds are permitted as separators from stdin . Stops read‐ ing stdin when an EOF is detected. See the DATA SUPPLIED section below." }, { "flag": "-d", "long": "--data", "arg": null, "description": "reads one or more data strings from the file called FN, limit almost 216 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." }, { "flag": "-D", "long": "--descriptor", "arg": null, "description": "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 de‐ scriptor 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." }, { "flag": "-x", "long": "--dsn", "arg": null, "description": "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 corre‐ sponding 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." }, { "flag": "-E", "long": "--eiioe", "arg": null, "description": "AF is either the string 'auto' or 'force'. There was some fuzziness in the interpre‐ tation of the 'element index' field in the Additional Element Status (AES) dpage be‐ tween 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 EI‐ IOE 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 in‐ dex 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 ef‐ fect. It is recommended that HP JBOD users set --eiioe=auto ." }, { "flag": "-e", "long": "--enumerate", "arg": null, "description": "enumerate all known diagnostic page (dpage) names and SES elements that this utility recognizes plus the abbreviations accepted by this utility. Ignores DEVICE if it is given. Essentially 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 in‐ formation, 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. \"sgses -ee -I ts\" to only show the acronyms asso‐ ciated with the Enclosure Control/Status dpage's Temperature Sensor Element Type)." }, { "flag": "-f", "long": "--filter", "arg": null, "description": "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 \"status=ok\" field (in the Enclosure status dpage) are output. The --filter option is useful for reducing the amount of output generated by the --join option." }, { "flag": "-G", "long": "--get", "arg": null, "description": "Used to read a field in a status element. Must be used together with a an indexing op‐ tion 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 Additional Ele‐ ment 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 FOR‐ MAT and the CLEAR, GET, SET sections below." }, { "flag": "-h", "long": "--help", "arg": null, "description": "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'." }, { "flag": "-H", "long": "--hex", "arg": null, "description": "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 com‐ ment." }, { "flag": "-I", "long": "--index", "arg": null, "description": "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 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." }, { "flag": "-I", "long": "--index", "arg": null, "description": "where TIA,II is an type header index (TI) or Element type abbreviation (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 enu‐ merate the available Element type abbreviations use the --enumerate option." }, { "flag": "-X", "long": "--inhex", "arg": null, "description": "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 sg3utils manpage for more in‐ formation." }, { "flag": "-i", "long": "--inner-hex", "arg": null, "description": "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." }, { "flag": "-j", "long": "--join", "arg": null, "description": "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 as‐ sociated 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 DE‐ SCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS sections below." }, { "flag": "-l", "long": "--list", "arg": null, "description": "This option is equivalent to --enumerate. See that option." }, { "flag": "-M", "long": "--mask", "arg": null, "description": "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 sgses 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 de‐ fault action (i.e. without this option) is to perform the mask step in the read-mask-modify-write sequence." }, { "flag": "-m", "long": "--maxlen", "arg": null, "description": "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)." }, { "flag": "-n", "long": "--nickname", "arg": null, "description": "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 NICK‐ NAME section below." }, { "flag": "-N", "long": "--nickid", "arg": null, "description": "where SEID is the Subenclosure identifier that the new Nickname (SEN) will be applied to. So SEID must be an existing Subenclosure identifier. The default value is 0 which is the main enclosure." }, { "flag": "-p", "long": "--page", "arg": null, "description": "where PG is a dpage 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 dpage 'sdp' which is pagecode 0 (i.e. \"Supported Diag‐ nostic 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." }, { "flag": "-q", "long": "--quiet", "arg": null, "description": "this suppresses the number of warnings and messages output. The exit status of the utility is unaffected by this option." }, { "flag": "-r", "long": "--raw", "arg": null, "description": "outputs the chosen status dpage in ASCII hex in a format suitable for a later invoca‐ tion 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 de‐ coded 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 output is treated, but not both." }, { "flag": "-R", "long": "--readonly", "arg": null, "description": "open the DEVICE read-only (e.g. in Unix with the ORDONLY flag). The default is to open it read-write." }, { "flag": "-A", "long": "--sas-addr", "arg": null, "description": "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 Additional 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 consecutively. 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 iden‐ tifier 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, DE‐ VICE SLOT NUMBER AND SAS ADDRESS section below." }, { "flag": "-S", "long": "--set", "arg": null, "description": "Used to set 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 CLEAR, GET, SET sections below." }, { "flag": "-s", "long": "--status", "arg": null, "description": "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 --con‐ trol or this option must be given to distinguish between the two different ways that data will be treated." }, { "flag": "-v", "long": "--verbose", "arg": null, "description": "increase the level of verbosity. For example when this option is given four times (in which case the short form is more convenient: '-vvvv') then if the internal join array has been generated then it is output to stderr in a form suitable for debugging." }, { "flag": "-V", "long": "--version", "arg": null, "description": "print the version string and then exit." }, { "flag": "-w", "long": "--warn", "arg": null, "description": "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 qual‐ ity of SES devices vary and to be fair, the descriptions from T10 drafts and standards have been tweaked several times (see the EIIOE field) in order to clear up confusion." } ], "examples": [ "Examples can also be found at http://sg.danny.cz/sg/sgses.html", "The following examples use Linux device names. For suitable device names in other supported", "Operating Systems see the sg3utils(8) man page.", "To view the supported dpages:", "sgses /dev/bsg/6:0:2:0", "To view the Configuration Diagnostic dpage:", "sgses --page=cf /dev/bsg/6:0:2:0", "To view the Enclosure Status dpage:", "sgses --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:", "sgses -p aes -D ArrayDevice07 -G atsasaddr -H /dev/sg3", "To collate the information in the Enclosure Status, Element Descriptor and Additional Element", "Status dpages the --join option can be used:", "sgses --join /dev/sg3", "This will produce a lot of output. To filter out lines that don't contain much information", "add the --filter option:", "sgses --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 precisely the carrier", "drawer the disk is in):", "sgses --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 invocation is equivalent to the previous one:", "sgses --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:", "sgses --descriptor=ArrayDevice07 --set=ident /dev/sg3", "To stop that LED flashing:", "sgses --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 di‐", "agnostic dpage. The String (In and Out) diagnostics dpage is relatively simple (compared with", "the Enclosure Status/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:", "sgses --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 repre‐", "senting a byte, 16 pairs per line, space separated. The redirection puts stdout in a file", "called \"t\":", "sgses --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 ed‐", "itor to change t. The changes can be sent to the device with:", "sgses --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:", "sgses --page=str /dev/bsg/6:0:2:0", "To change the nickname on the main enclosure:", "sgses --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:", "sgses --page=all -HHHH /dev/sg5 > encsg5all.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 redirected). A text editor could be used to inspect", "encsg5all.hex . If all looks in order at some later time, potentially on a different ma‐", "chine where encsg5all.hex has been copied, a \"join\" could be done. Note that join reflects", "the state of the enclosure when the capture was done.", "sgses --data=@encsg5all.hex --status --join" ], "see_also": [] }