xref: /openbmc/docs/host-management.md (revision 3e453fe5) 
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/xyz/openbmc_project/Control/Boot/Mode.interface.yaml)
181and
182[`BootSource`](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Control/Boot/Source.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/one_time/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/one_time/attr/BootSource -d '{"data": "xyz.openbmc_project.Control.Boot.Source.Sources.Default"}'
194    ```
195
196## Host State Control
197
198The host can be controlled through the `host` object. The object implements a
199number of actions including power on and power off. These correspond to the IPMI
200`power on` and `power off` commands.
201
202Assuming you have logged in, the following will power on the host:
203
204```
205$ 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
206```
207
208To power off the host:
209
210```
211$ 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
212```
213
214To issue a hard power off (accomplished by powering off the chassis):
215
216```
217$ 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
218```
219
220To reboot the host:
221
222```
223$ 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
224```
225
226
227More information about Host State Management can be found here:
228https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/xyz/openbmc_project/State
229
230## Host Clear GARD
231
232On OpenPOWER systems, the host maintains a record of bad or non-working
233components on the GARD partition. This record is referenced by the host on
234subsequent boots to determine which parts should be ignored.
235
236The BMC implements a function that simply clears this partition. This function
237can be called as follows:
238
239  * Method 1: From the BMC command line:
240
241      ```
242      busctl call org.open_power.Software.Host.Updater \
243        /org/open_power/control/gard \
244        xyz.openbmc_project.Common.FactoryReset Reset
245      ```
246
247  * Method 2: Using the REST API:
248
249      ```
250      $ 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
251      ```
252
253Implementation: https://github.com/openbmc/openpower-pnor-code-mgmt
254
255## Host Watchdog
256
257The host watchdog service is responsible for ensuring the host starts and boots
258within a reasonable time. On host start, the watchdog is started and it is
259expected that the host will ping the watchdog via the inband interface
260periodically as it boots. If the host fails to ping the watchdog within the
261timeout then the host watchdog will start a systemd target to go to the quiesce
262target. System settings will then determine the recovery behavior from that
263state, for example, attempting to reboot the system.
264
265The host watchdog utilizes the generic [phosphor-watchdog][1] repository. The
266host watchdog service provides 2 files as configuration options into
267phosphor-watchdog:
268
269    /lib/systemd/system/phosphor-watchdog@poweron.service.d/poweron.conf
270    /etc/default/obmc/watchdog/poweron
271
272`poweron.conf` contains the "Conflicts" relationships to ensure the watchdog
273service is stopped at the correct times. `poweron` contains the required
274information for phosphor-watchdog (more information on these can be found in the
275[phosphor-watchdog][1] repository).
276
277The 2 service files involved with the host watchdog are:
278
279    phosphor-watchdog@poweron.service
280    obmc-enable-host-watchdog@0.service
281
282`phosphor-watchdog@poweron` starts the host watchdog service and
283`obmc-enable-host-watchdog` starts the watchdog timer. Both are run as a part
284of the `obmc-host-startmin@.target`. Service dependencies ensure the service is
285started before the enable is called.
286
287The default watchdog timeout can be found within the [dbus interface
288specification][2] (Interval property).
289
290The host controls the watchdog timeout and enable/disable once it starts.
291
292[1]: https://github.com/openbmc/phosphor-watchdog
293[2]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/State/Watchdog.interface.yaml
294