1Host Management with OpenBMC 2============================ 3 4This document describes the host-management interfaces of the OpenBMC object 5structure, accessible over REST. 6 7Inventory 8--------- 9 10The system inventory structure is under the `/org/openbmc/inventory` hierarchy. 11 12In OpenBMC the inventory is represented as a path which is hierarchical to the 13physical system topology. Items in the inventory are referred to as inventory 14items and are not necessarily FRUs. If the system contains one chassis, a 15motherboard, and a CPU on the motherboard, then the path to that inventory item 16would be: 17 18 inventory/system/chassis0/motherboard0/cpu0 19 20The properties associated with an inventory item are specific to that item with 21the addition of these common properties: 22 23 * `version`: a code version associated with this item 24 * `fault`: indicates whether this item has reported an error condition (True/False) 25 * `present`: indicates whether this item is present in the system (True/False) 26 27The usual `list` and `enumerate` REST queries allow the system inventory 28structure to be accessed. For example, to enumerate all inventory items and 29their properties: 30 31 curl -b cjar -k https://bmc/org/openbmc/inventory/enumerate 32 33To list the properties of one item: 34 35 curl -b cjar -k https://bmc/org/openbmc/inventory/system/chassis/motherboard 36 37Sensors 38------- 39 40The system inventory structure is under the `/org/openbmc/sensors` hierarchy. 41 42This interface allows monitoring of system attributes like temperature or 43altitude, and are represented similar to the inventory, by object paths under 44the top-level `sensors` object name. The path categorizes the sensor and shows 45what the sensor represents, but does not necessarily represent the physical 46topology of the system. 47 48For example, all temperature sensors are under `sensors/temperature`. CPU 49temperature sensors would be `sensors/temperature/cpu[n]`. 50 51These are the common properties associated all sensors: 52 53 * `value`: current value of sensor 54 * `units`: units of value 55 * `warning_upper` & `warning_lower`: upper & lower threshold for a warning error 56 * `critical_upper` & `critical_lower`: upper & lower threshold for a critical error 57 * `threshold_state`: current threshold state (normal, warning, critical) 58 * `worst_threshold_state`: highest threshold state seen for all time. There is 59 a REST call to reset this state to normal. 60 61Unlike IPMI, there are no "functional" sensors in OpenBMC; functional states are 62represented in the inventory. 63 64To enumerate all sensors in the system: 65 66 curl -c cjar -k https://bmc/org/openbmc/sensors/enumerate 67 68List properties of one inventory item: 69 70 curl -c cjar -k https://bmc/org/openbmc/sensors/temperature/ambient 71 72Event Logs 73---------- 74 75The event log structure is under the `/org/openbmc/records/events` hierarchy. 76Each event is a separate object under this structure, referenced by number. 77 78BMC and host firmware on POWER-based servers can report logs to the BMC. 79Typically, these logs are reported in cases where host firmware cannot start the 80OS, or cannot reliably log to the OS. 81 82The properties associated with an error log are as follows: 83 84 * `Association`: a uri to the failing inventory part 85 * `Message`: An English text string indicating the failure 86 * `Reported By`: Firmware region that created the log ('Host', 'BMC') 87 * `Severity`: level of problem (Info, Predictive Error, etc) 88 * `Development Data`: Data dump for use by Development to analyze the failure 89 90To list all reported events: 91 92 $ curl -b cjar -k https://bmc/org/openbmc/records/events/ 93 { 94 "data": [ 95 "/org/openbmc/records/events/1", 96 "/org/openbmc/records/events/2", 97 "/org/openbmc/records/events/3", 98 ], 99 "message": "200 OK", 100 "status": "ok" 101 } 102 103To read a specific event log: 104 105 $ curl -b cjar -k https://bmc/org/openbmc/records/events/1 106 { 107 "data": { 108 "association": "/org/openbmc/inventory/system/systemevent", 109 "debug_data": [ ... ], 110 "message": "A systemevent has experienced a unrecoverable error", 111 "reported_by": "Host", 112 "severity": "unrecoverable error", 113 "time": "2016:05:04 01:43:57" 114 }, 115 "message": "200 OK", 116 "status": "ok" 117 } 118 119To delete an event log (log 1 in his example), call the `delete` method on the event: 120 121 curl -b cjar -k -H "Content-Type: application/json" -X POST \ 122 -d '{"data" : []}' \ 123 https://bmc/org/openbmc/records/events/1/action/delete 124 125To clear all logs, call the top-level `clear` method: 126 127 curl -b cjar -k -H "Content-Type: application/json" -X POST \ 128 -d '{"data" : []}' \ 129 https://bmc/org/openbmc/records/events/action/clear 130 131BIOS boot options 132----------------- 133 134With OpenBMC, the BIOS boot options are stored as dbus properties under the 135`settings/host0` path, in the `boot_flags` property. Their format adheres to the 136Boot Options Parameters table specified in the IPMI Specification Document, 137section 28.13. 138 139Each boot parameter is represented by an individual property, and their hex 140value is displayed in a string format. For example, a boot flags parameter value 141of `0x8014000000` would be stored as a `8014000000` string in the 142`settings/host0/boot_flags` property. 143