xref: /openbmc/docs/host-management.md (revision 309abc9187735439077138246f0e657aad902789) 
1# Host Management with OpenBMC
2
3This document describes the host-management interfaces of the OpenBMC object
4structure, accessible over REST.
5
6Note: Authentication
7
8See the details on authentication at
9[REST-cheatsheet](https://github.com/openbmc/docs/blob/master/REST-cheatsheet.md#establish-rest-connection-session).
10
11This document uses token based authentication method:
12
13```bash
14export bmc=xx.xx.xx.xx
15export token=`curl -k -H "Content-Type: application/json" -X POST https://${bmc}/login -d '{"username" :  "root", "password" :  "0penBmc"}' | grep token | awk '{print $2;}' | tr -d '"'`
16curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/...
17```
18
19## Inventory
20
21The system inventory structure is under the `/xyz/openbmc_project/inventory`
22hierarchy.
23
24In OpenBMC the inventory is represented as a path which is hierarchical to the
25physical system topology. Items in the inventory are referred to as inventory
26items and are not necessarily FRUs (field-replaceable units). If the system
27contains one chassis, a motherboard, and a CPU on the motherboard, then the path
28to that inventory item would be:
29
30`inventory/system/chassis0/motherboard0/cpu0`
31
32The properties associated with an inventory item are specific to that item. Some
33common properties are:
34
35- `Version`: A code version associated with this item.
36- `Present`: Indicates whether this item is present in the system (True/False).
37- `Functional`: Indicates whether this item is functioning in the system
38  (True/False).
39
40The usual `list` and `enumerate` REST queries allow the system inventory
41structure to be accessed. For example, to enumerate all inventory items and
42their properties:
43
44```bash
45curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/inventory/enumerate
46```
47
48To list the properties of one item:
49
50```bash
51curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/inventory/system/chassis/motherboard
52```
53
54## Sensors
55
56The system sensor structure is under the `/xyz/openbmc_project/sensors`
57hierarchy.
58
59This interface allows monitoring of system attributes like temperature or
60altitude, and are represented similar to the inventory, by object paths under
61the top-level `sensors` object name. The path categorizes the sensor and shows
62what the sensor represents, but does not necessarily represent the physical
63topology of the system.
64
65For example, all temperature sensors are under `sensors/temperature`. CPU
66temperature sensors would be `sensors/temperature/cpu[n]`.
67
68These are some common properties:
69
70- `Value`: Current value of the sensor
71- `Unit`: Unit of the value and "Critical" and "Warning" values
72- `Scale`: The scale of the value and "Critical" and "Warning" values
73- `CriticalHigh` & `CriticalLow`: Sensor device upper/lower critical threshold
74  bound
75- `CriticalAlarmHigh` & `CriticalAlarmLow`: True if the sensor has exceeded the
76  critical threshold bound
77- `WarningHigh` & `WarningLow`: Sensor device upper/lower warning threshold
78  bound
79- `WarningAlarmHigh` & `WarningAlarmLow`: True if the sensor has exceeded the
80  warning threshold bound
81
82A temperature sensor might look like:
83
84```bash
85    curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/sensors/temperature/ocp_zone
86    {
87      "data": {
88        "CriticalAlarmHigh": false,
89        "CriticalAlarmLow": false,
90        "CriticalHigh": 65000,
91        "CriticalLow": 0,
92        "Functional": true,
93        "MaxValue": 0,
94        "MinValue": 0,
95        "Scale": -3,
96        "Unit": "xyz.openbmc_project.Sensor.Value.Unit.DegreesC",
97        "Value": 34625,
98        "WarningAlarmHigh": false,
99        "WarningAlarmLow": false,
100        "WarningHigh": 63000,
101        "WarningLow": 0
102      },
103      "message": "200 OK",
104      "status": "ok"
105    }
106```
107
108Note the value of this sensor is 34.625C (34625 \* 10^-3).
109
110Unlike IPMI, there are no "functional" sensors in OpenBMC; functional states are
111represented in the inventory.
112
113To enumerate all sensors in the system:
114
115```bash
116curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/sensors/enumerate
117```
118
119List properties of one inventory item:
120
121```bash
122curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/sensors/temperature/outlet
123```
124
125## Event Logs
126
127The event log structure is under the `/xyz/openbmc_project/logging/entry`
128hierarchy. Each event is a separate object under this structure, referenced by
129number.
130
131BMC and host firmware on POWER-based servers can report event logs to the BMC.
132Typically, these event logs are reported in cases where host firmware cannot
133start the OS, or cannot reliably log to the OS.
134
135The properties associated with an event log are as follows:
136
137- `Message`: The type of event log (e.g.
138  "xyz.openbmc_project.Inventory.Error.NotPresent").
139- `Resolved` : Indicates whether the event has been resolved.
140- `Severity`: The level of problem ("Info", "Error", etc.).
141- `Timestamp`: The date of the event log in epoch time.
142- `Associations`: A URI to the failing inventory part.
143
144To list all reported event logs:
145
146```bash
147    curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/logging/entry
148    {
149      "data": [
150        "/xyz/openbmc_project/logging/entry/3",
151        "/xyz/openbmc_project/logging/entry/2",
152        "/xyz/openbmc_project/logging/entry/1",
153        "/xyz/openbmc_project/logging/entry/7",
154        "/xyz/openbmc_project/logging/entry/6",
155        "/xyz/openbmc_project/logging/entry/5",
156        "/xyz/openbmc_project/logging/entry/4"
157      ],
158      "message": "200 OK",
159      "status": "ok"
160    }
161```
162
163To read a specific event log:
164
165```bash
166    curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/logging/entry/1
167    {
168      "data": {
169        "AdditionalData": [
170          "_PID=183"
171        ],
172        "Id": 1,
173        "Message": "xyz.openbmc_project.Common.Error.InternalFailure",
174        "Purpose": "xyz.openbmc_project.Software.Version.VersionPurpose.BMC",
175        "Resolved": false,
176        "Severity": "xyz.openbmc_project.Logging.Entry.Level.Error",
177        "Timestamp": 1563191362822,
178        "Version": "2.8.0-dev-132-gd1c1b74-dirty",
179        "associations": []
180      },
181      "message": "200 OK",
182      "status": "ok"
183    }
184```
185
186To delete an event log (log 1 in this example), call the `Delete` method on the
187event:
188
189```bash
190curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST -d '{"data" : []}' https://${bmc}/xyz/openbmc_project/logging/entry/1/action/Delete
191```
192
193To clear all event logs, call the top-level `DeleteAll` method:
194
195```bash
196curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST -d '{"data" : []}' https://${bmc}/xyz/openbmc_project/logging/action/DeleteAll
197```
198
199## Host Boot Options
200
201With OpenBMC, the Host boot options are stored as D-Bus properties under the
202`control/host0/boot` path. Properties include
203[`BootMode`](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Control/Boot/Mode.interface.yaml),
204[`BootSource`](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Control/Boot/Source.interface.yaml)
205and if the host is based on x86 CPU also
206[`BootType`](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Control/Boot/Type.interface.yaml).
207
208- Set boot mode:
209
210```bash
211curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/attr/BootMode -d '{"data": "xyz.openbmc_project.Control.Boot.Mode.Modes.Regular"}'
212```
213
214- Set boot source:
215
216```bash
217curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/attr/BootSource -d '{"data": "xyz.openbmc_project.Control.Boot.Source.Sources.Default"}'
218```
219
220- Set boot type (valid only if host is based on the x86 CPU):
221
222```bash
223curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/attr/BootType -d '{"data": "xyz.openbmc_project.Control.Boot.Type.Types.EFI"}'
224```
225
226Also there are boolean
227[`Enable`](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Object/Enable.interface.yaml)
228properties that control if the boot source override is persistent or one-time,
229and if the override is enabled or not.
230
231- Set boot override one-time flag:
232
233```bash
234curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/one_time/attr/Enabled -d '{"data": "true"}'
235```
236
237- Enable boot override:
238
239```bash
240curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/attr/Enabled -d '{"data": "true"}'
241```
242
243## Host State Control
244
245The host can be controlled through the `host` object. The object implements a
246number of actions including power on and power off. These correspond to the IPMI
247`power on` and `power off` commands.
248
249Assuming you have logged in, the following will power on the host:
250
251```bash
252curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -d '{"data": "xyz.openbmc_project.State.Host.Transition.On"}' -X PUT https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
253```
254
255To power off the host:
256
257```bash
258curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -d '{"data": "xyz.openbmc_project.State.Host.Transition.Off"}' -X PUT https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
259```
260
261To issue a hard power off (accomplished by powering off the chassis):
262
263```bash
264curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data":"xyz.openbmc_project.State.Chassis.Transition.Off"}' https://${bmc}//xyz/openbmc_project/state/chassis0/attr/RequestedPowerTransition
265```
266
267To reboot the host:
268
269```bash
270curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data":"xyz.openbmc_project.State.Host.Transition.Reboot"}' https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
271```
272
273More information about Host State Management can be found here:
274<https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/State>
275
276## Host Clear GARD
277
278On OpenPOWER systems, the host maintains a record of bad or non-working
279components on the GARD partition. This record is referenced by the host on
280subsequent boots to determine which parts should be ignored.
281
282The BMC implements a function that simply clears this partition. This function
283can be called as follows:
284
285- Method 1: From the BMC command line:
286
287```bash
288  busctl call org.open_power.Software.Host.Updater \
289    /org/open_power/control/gard \
290    xyz.openbmc_project.Common.FactoryReset Reset
291```
292
293- Method 2: Using the REST API:
294
295```bash
296curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST -d '{"data":[]}' https://${bmc}/org/open_power/control/gard/action/Reset
297```
298
299Implementation: <https://github.com/openbmc/openpower-pnor-code-mgmt>
300
301## Host Watchdog
302
303The host watchdog service is responsible for ensuring the host starts and boots
304within a reasonable time. On host start, the watchdog is started and it is
305expected that the host will ping the watchdog via the inband interface
306periodically as it boots. If the host fails to ping the watchdog within the
307timeout then the host watchdog will start a systemd target to go to the quiesce
308target. System settings will then determine the recovery behavior from that
309state, for example, attempting to reboot the system.
310
311The host watchdog utilizes the generic [phosphor-watchdog][1] repository. The
312host watchdog service provides 2 files as configuration options into
313phosphor-watchdog:
314
315```text
316    /lib/systemd/system/phosphor-watchdog@poweron.service.d/poweron.conf
317    /etc/default/obmc/watchdog/poweron
318```
319
320`poweron.conf` contains the "Conflicts" relationships to ensure the watchdog
321service is stopped at the correct times. `poweron` contains the required
322information for phosphor-watchdog (more information on these can be found in the
323[phosphor-watchdog][1] repository).
324
325The 2 service files involved with the host watchdog are:
326
327```text
328    phosphor-watchdog@poweron.service
329    obmc-enable-host-watchdog@0.service
330```
331
332`phosphor-watchdog@poweron` starts the host watchdog service and
333`obmc-enable-host-watchdog` starts the watchdog timer. Both are run as a part of
334the `obmc-host-startmin@.target`. Service dependencies ensure the service is
335started before the enable is called.
336
337The default watchdog timeout can be found within the [dbus interface
338specification][2] (Interval property).
339
340The host controls the watchdog timeout and enable/disable once it starts.
341
342[1]: https://github.com/openbmc/phosphor-watchdog
343[2]:
344  https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/Watchdog.interface.yaml
345