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