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