=======Sensors Technical Specification 3.0.0 Released 09 March 2004 Written by Douglas Bone and Joe Ruscio Please send comments to the following distribution list: address@hidden address@hidden address@hidden address@hidden address@hidden address@hidden address@hidden address@hidden address@hidden Changes from 3.1: 1. Added clarification that multigroup queries are currently supported only through the use of an alias at the current time. I. Introduction This software (ipmi-sensors) fulfills the requirements of section 3.3.3 "Linux Access to Motherboard Sensors" in the Thunder Statement of Work (SOW). 1.1 Purpose Ipmi-sensors is invoked from the Linux command line and provides human-readable output of node sensor information. 1.2 Scope Ipmi-sensors provides output in human-readable form. APIs for SNMP agents are provided separately through libfreeipmi. 1.3 Background Ipmi-sensors works in conjunction with libfreeipmi and FISH (free ipmi shell) to provide access to motherboard sensors. Tiger4 compute nodes implement a superset of the IPMI 1.5 specification. There are 134 sensors integrated into the Tiger4 system, most of which provide real-time status information. 1.4 References/Related Documents IPMI 1.5 specifications section 36.2 (list of sensors). 2. Design Overview Ipmi-sensors is a executable using the FreeIPMI Shell (FISH) running on the Chaos 2.0 Linux distribution on California Digital 6440 systems. Ipmi-sensors should be installed in $(prefix)/sbin. FISH and libfreeipmi need to be installed on the system. When ipmi-sensors is invoked, it uses the system's baseboard management controller (BMC) to query the system's sensors using IPMI 1.5-based libfreeipmi in-band KCS driver. The KCS device driver polls the KCS registers at a interval defined in the $(prefix)/etc/fish.scm configuration file to acquire sensor data. Ipmi-sensors acquires information about sensors from the sensor data repository in the BMC's flash memory and uses that information to acquire and interpret data from specified sensors. Current sensor information is then compared to the threshold values defined in the SDR and a computation is undertaken to see if the sensor reading is acceptable (within permitted band) or if an alert condition exists (for example if a threshold based sensor reading is below low critical threshold or above high critical threshold). 3. Dependency Description Requires libfreeipmi and FISH. Validated on CHAOS 2.0 Linux distribution on California Digital 6440 system. 4.Interface Description sensors When invoked without arguments, ipmi-sensors displays abbreviated information about each sensor which returns a valid reading. -l, --list-groups Lists sensors groups defined in either the systems SDR or as aliased in the sensors.sem configuration file. -v, --verbose Provides verbose output. More complete information than in default output. Includes sensor minimum and maximum reading. -vv Provides very verbose output. Suppresses debugging information, so for many sensors output will not differ from verbose output. When used alone to display very verbose output for all sensors it will also display the available sensors for 108-134, which are not currently valid on the Tiger4 node. -s "SENSORS-LIST", --sensors="SENSORS-LIST" Query sensors specifically enumerated in a space-delimited sensor list. Sensors are referred to by sensor record number expressed as a decimal number. Sensor values must be integers between 1 and 134 inclusive. Will have no effect if invoked along with the --group option. When specifying multiple single letter options with s, the s must be the last option specified, for example "sensors -vs", not "sensors -sv" -g , --group= Allows specification of sensors by their SDR-based group names. GROUP-NAME is defined in the IPMI specification or aliased in the $prefix/etc/fish/sensors-conf.scm configuration file to an SDR-defined group. Multiple groups can be queried at the same time only though use of an alias. Can be used with -v and -vv options. Valid group names are those defined in the IPMI specification. Group names including spaces must be enclosed within either single or double quotation marks. They are as follows: Unknown Temperature Voltage Current Fan Platform Chassis Intrusion Platform Security Violation Processor Power Supply Power Unit Cooling Device FRU Sensor Memory Drive Slot Post Memory Resize System Firmware Event Logging Disabled Watchdog1 System Event Critical Interrupt Button Board Microcontroller Add In Card Chassis Chip Set Other Fru Cable Interconnect Terminator System Boot Initiated Boot Error OS Boot OS Critical Stop Slot Connector ACPI Power State Watchdog 2 Platform Alert Entity Presence Monitor Asic LAN Management Subsystem Health Battery Session Audit Version Change FRU State OEM Reserved -i, --sdr-info Show SDR Info. Displays information about the SDR including the number of records present, the amount of space remaining, the SDR version number, the last date a record was added, and the last date a record was deleted. -f, --flush-cache Flushes the SDR cache. The next invocation of the sensors utility will rebuild the SDR cache with the current values in the SDR. -p, --prof Also reports the KCS poll count for a sensor reading. This information can be used when tuning the default polling interval. -u, --usage Returns usage information. -h, --help Provides help. -V, --version Returns version information. 5. Examples Ipmi-sensors would normally be invoked to inquire about the operating environment within a compute node. sensors Queries all valid sensors and displays a one line summary for each one. sensors --group Processor Queries all processor-related sensors. sensors -vs "30 54" Provides verbose output of sensors 30 and 54. 6. I/O 6.1 Exit status Ipmi-sensors shall exit with status 0 if successful and exit with a nonzero status if unsuccessful. 6.2 Output Ipmi-sensors directs output and errors to stdout and stderr. Output verbosity is controlled by using the default, -v (verbose), or -vv (very verbose) options. 6.2.1 Default output Output format will vary depending upon the type of sensor being queried. In all threshold sensors, the default output will comprise a single line per sensor and include sensor record number, sensor name, current sensor reading (if available), sensor lower critical threshold (if available), sensor nominal value (if available), and sensor high critical threshold (if available). The current sensor value will be compared to upper and lower critical thresholds and reported as "OK" at the end of the line if the value lies between the low and high critical thresholds, as "ALERT" if the current reading is below the low critical threshold or above the high critical threshold, or as "UNKNOWN" if either the threshold or sensor values are not known. In all discrete sensors the default output will comprise of a single line per sensor and include sensor record number, sensor name, and current sensor value. Many discrete sensors maintain the state of several options and "OK" will only be reported if all are in an "OK" state. Output will be one sensor per line listed in increasing sensor record number order. >sensors -s "44" 44: Proc 1 Temp (Temperature): 59.00 C (low=10.00/nom=85.00/high=105.00) [OK] 6.2.2 Verbose output The verbose format will provide multi-line output with more complete information, including sensor minimum and maximum readings with more complete unit information. >sensors -vs "44" Record ID: 44 Sensor type: Proc 1 Temp (Temperature) Sensor number: #152 Event/Reading type code: 01h Lower non-recoverable threshold: 0.00 Degrees C Upper non-recoverable threshold: 0.00 Degrees C Lower Critical threshold: 5.00 Degrees C Upper Critical threshold: 115.00 Degrees C Lower non-critical threshold: 9.00 Degrees C Upper non-critical threshold: 110.00 Degrees C Sensor min. reading: 128.00 Degrees C Sensor max. reading: 127.00 Degrees C Normal min.: 10.00 Degrees C Nominal reading: 85.00 Degrees C Normal max: 105.00 Degrees C Sensor reading: 59.00 Degrees C 6.2.3 Very verbose output The very verbose format reports the entire contents of the system's SDR (sensor data repository) for the specified sensor(s). >sensors -vv -s "44" Record ID: 44 Sensor type: Proc 1 Temp (Temperature) Sensor number: #152 Event/Reading type code: 01h Lower non-recoverable threshold: 0.00 Degrees C Upper non-recoverable threshold: 0.00 Degrees C Lower Critical threshold: 5.00 Degrees C Upper Critical threshold: 115.00 Degrees C Lower non-critical threshold: 9.00 Degrees C Upper non-critical threshold: 110.00 Degrees C Sensor min. reading: 128.00 Degrees C Sensor max. reading: 127.00 Degrees C Normal min.: 10.00 Degrees C Nominal reading: 85.00 Degrees C Normal max: 105.00 Degrees C Sensor reading: 58.00 Degrees C 6.3 Group output If the --group option is specified along with a GROUP-NAME, only those sensors belonging to GROUP-NAME will be included. Example output for sensors --group "Fan" might be as follows: 33: F38 Tach Fan 1 (Fan): 2700.00 RPM (low=2260.00/nom=2600.00/high=2880.00) [OK] 34: F38 Tach Fan 2 (Fan): 2720.00 RPM (low=2260.00/nom=2600.00/high=2880.00) [OK] 35: F25 Tach Fan 3 (Fan): 2460.00 RPM (low=2160.00/nom=2500.00/high=2780.00) [OK] 36: F25 Tach Fan 4 (Fan): 2500.00 RPM (low=2260.00/nom=2620.00/high=2900.00) [OK] 83: Fan 1 Present (Fan): [Device Inserted/Device Present] 84: Fan 2 Present (Fan): [Device Inserted/Device Present] 85: Fan 3 Present (Fan): [Device Inserted/Device Present] 86: Fan 4 Present (Fan): [Device Inserted/Device Present] 6.4 List-groups output List-groups will output a list of groups such as that shown in section 4 under the --group example as well as any user-aliased group names in the sensors.scm configuration file. 6.5 Profile output The --prof option will also report the kcs-poll-count. A line of the following form is appended to any other output generated by the sensors command: Pro kcs-poll-count = 174 7. Additional Design Considerations The process shall be lightweight so as to not impair CPU performance. Data should be returned quickly enough to meet the needs of human operators invoking the command from a command-line prompt. Accordingly, the contents of the SDR will be cached so only the actual sensor readings themselves need be queried.