xref: /openbmc/docs/host-management.md (revision ef31648c) 
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 `/xyz/openbmc_project/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 (field-replaceable units). If the system
15contains one chassis, a motherboard, and a CPU on the motherboard, then the
16path to that inventory item would be:
17
18   inventory/system/chassis0/motherboard0/cpu0
19
20The properties associated with an inventory item are specific to that item.
21Some common properties are:
22
23 * `Version`: A code version associated with this item.
24 * `Present`: Indicates whether this item is present in the system (True/False).
25 * `Functional`: Indicates whether this item is functioning 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}/xyz/openbmc_project/inventory/enumerate
32
33To list the properties of one item:
34
35    curl -b cjar -k https://${bmc}/xyz/openbmc_project/inventory/system/chassis/motherboard
36
37Sensors
38-------
39
40The system sensor structure is under the `/xyz/openbmc_project/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 some common properties:
52
53 * `Value`: Current value of the sensor
54 * `Unit`: Unit of the value and "Critical" and "Warning" values
55 * `Scale`: The scale of the value and "Critical" and "Warning" values
56 * `CriticalHigh` & `CriticalLow`: Sensor device upper/lower critical threshold bound
57 * `CriticalAlarmHigh` & `CriticalAlarmLow`: True if the sensor has exceeded the
58critical threshold bound
59 * `WarningHigh` & `WarningLow`: Sensor device upper/lower warning threshold bound
60 * `WarningAlarmHigh` & `WarningAlarmLow`: True if the sensor has exceeded the
61warning threshold bound
62
63A temperature sensor might look like:
64
65    curl -b cjar -k https://${bmc}/xyz/openbmc_project/sensors/temperature/pcie
66    {
67      "data": {
68        "CriticalAlarmHigh": 0,
69        "CriticalAlarmLow": 0,
70        "CriticalHigh": 70000,
71        "CriticalLow": 0,
72        "Scale": -3,
73        "Unit": "xyz.openbmc_project.Sensor.Value.Unit.DegreesC",
74        "Value": 28187,
75        "WarningAlarmHigh": 0,
76        "WarningAlarmLow": 0,
77        "WarningHigh": 60000,
78        "WarningLow": 0
79      },
80      "message": "200 OK",
81      "status": "ok"
82    }
83
84Note the value of this sensor is 28.187C (28187 * 10^-3).
85
86Unlike IPMI, there are no "functional" sensors in OpenBMC; functional states are
87represented in the inventory.
88
89To enumerate all sensors in the system:
90
91    curl -b cjar -k https://${bmc}/xyz/openbmc_project/sensors/enumerate
92
93List properties of one inventory item:
94
95    curl -b cjar -k https://${bmc}/xyz/openbmc_project/sensors/temperature/ambient
96
97Event Logs
98----------
99
100The event log structure is under the `/xyz/openbmc_project/logging/entry` hierarchy.
101Each event is a separate object under this structure, referenced by number.
102
103BMC and host firmware on POWER-based servers can report event logs to the BMC.
104Typically, these event logs are reported in cases where host firmware cannot start the
105OS, or cannot reliably log to the OS.
106
107The properties associated with an event log are as follows:
108
109 * `Message`: The type of event log (e.g. "xyz.openbmc_project.Inventory.Error.NotPresent").
110 * `Resolved` : Indicates whether the event has been resolved.
111 * `Severity`: The level of problem ("Info", "Error", etc.).
112 * `Timestamp`: The date of the event log in epoch time.
113 * `associations`: A URI to the failing inventory part.
114
115To list all reported event logs:
116
117    $ curl -b cjar -k https://${bmc}/xyz/openbmc_project/logging/entry/
118    {
119      "data": [
120        "/xyz/openbmc_project/logging/entry/3",
121        "/xyz/openbmc_project/logging/entry/2",
122        "/xyz/openbmc_project/logging/entry/1",
123        "/xyz/openbmc_project/logging/entry/7",
124        "/xyz/openbmc_project/logging/entry/6",
125        "/xyz/openbmc_project/logging/entry/5",
126        "/xyz/openbmc_project/logging/entry/4"
127      ],
128      "message": "200 OK",
129      "status": "ok"
130    }
131
132To read a specific event log:
133
134    $ curl -b cjar -k https://${bmc}/xyz/openbmc_project/logging/entry/1
135    {
136      "data": {
137        "AdditionalData": [
138          "CALLOUT_INVENTORY_PATH=/xyz/openbmc_project/inventory/system/chassis/powersupply0",
139          "_PID=1136"
140        ],
141        "Id": 1,
142        "Message": "xyz.openbmc_project.Inventory.Error.NotPresent",
143        "Resolved": 0,
144        "Severity": "xyz.openbmc_project.Logging.Entry.Level.Error",
145        "Timestamp": 1512154612660,
146        "associations": [
147          [
148            "callout",
149            "fault",
150            "/xyz/openbmc_project/inventory/system/chassis/powersupply0"
151          ]
152        ]
153      },
154      "message": "200 OK",
155      "status": "ok"
156    }
157
158To delete an event log (log 1 in this example), call the `delete` method on the event:
159
160    curl -b cjar -k -H "Content-Type: application/json" -X POST \
161        -d '{"data" : []}' \
162        https://${bmc}/xyz/openbmc_project/logging/entry/1/action/Delete
163
164To clear all event logs, call the top-level `deleteAll` method:
165
166    curl -b cjar -k -H "Content-Type: application/json" -X POST \
167        -d '{"data" : []}' \
168        https://${bmc}/xyz/openbmc_project/logging/action/deleteAll
169
170Host Boot Options
171-----------------
172
173With OpenBMC, the Host boot options are stored as D-Bus properties under the
174`control/host0/boot` path. Properties include
175[`BootMode`](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Control/Boot/Mode.interface.yaml)
176and
177[`BootSource`](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Control/Boot/Source.interface.yaml).
178
179
180Host State Control
181------------------
182
183The host can be controlled through the `host` object. The object implements a number
184of actions including power on and power off. These correspond to the IPMI
185`power on` and `power off` commands.
186
187Assuming you have logged in, the following will power on the host:
188
189```
190curl -c cjar -b cjar -k -H "Content-Type: application/json" -X PUT \
191  -d '{"data": "xyz.openbmc_project.State.Host.Transition.On"}' \
192  https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
193```
194
195To power off the host:
196
197```
198curl -c cjar -b cjar -k -H "Content-Type: application/json" -X PUT \
199  -d '{"data": "xyz.openbmc_project.State.Host.Transition.Off"}' \
200  https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
201```
202
203To issue a hard power off (accomplished by powering off the chassis):
204
205```
206curl -c cjar -b cjar -k -H "Content-Type: application/json" -X PUT \
207  -d '{"data": "xyz.openbmc_project.State.Chassis.Transition.Off"}' \
208  https://${bmc}/xyz/openbmc_project/state/chassis0/attr/RequestedPowerTransition
209```
210
211To reboot the host:
212
213```
214curl -c cjar -b cjar -k -H "Content-Type: application/json" -X PUT \
215  -d '{"data": "xyz.openbmc_project.State.Host.Transition.Reboot"}' \
216  https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
217```
218
219
220More information about Host State Management can be found here:
221https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/xyz/openbmc_project/State
222
223Host Clear GARD
224================
225
226On OpenPOWER systems, the host maintains a record of bad or non-working
227components on the GARD partition. This record is referenced by the host on
228subsequent boots to determine which parts should be ignored.
229
230The BMC implements a function that simply clears this partition. This function
231can be called as follows:
232
233  * Method 1: From the BMC command line:
234
235      ```
236      busctl call org.open_power.Software.Host.Updater \
237        /org/open_power/control/gard \
238        xyz.openbmc_project.Common.FactoryReset Reset
239      ```
240
241  * Method 2: Using the REST API:
242
243      ```
244      curl -b cjar -k -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/org/open_power/control/gard/action/Reset
245      ```
246
247Implementation: https://github.com/openbmc/openpower-pnor-code-mgmt
248