1# OpenBMC REST cheat sheet 2 3This document is intended to provide a set of REST client commands for OpenBMC 4usage. OpenBMC REST is disabled by default in bmcweb. For more information, see 5<https://github.com/openbmc/bmcweb/commit/47c9e106e0057dd70133d50e928e48cbc68e709a>. 6Most of the functionality previously provided by OpenBMC REST is available in 7Redfish. 8 9## Using CURL commands 10 11### Notes on authentication 12 13The original REST server, from the phosphor-rest-server repository, uses 14authentication handled by the curl cookie jar files. The bmcweb REST server can 15use the same cookie jar files for read-only REST methods like GET, but requires 16either an authentication token or the username and password passed in as part of 17the URL for non-read-only methods. 18 19Starting with the 2.7 OpenBMC release (August 2019), bmcweb is the default REST 20server. The phosphor-rest-server repository was archived in October 2022. 21 22### Establish REST connection session 23 24- Using just the cookie jar files for the phosphor-rest server: 25 26```bash 27 export bmc=xx.xx.xx.xx 28 curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST https://${bmc}/login -d "{\"data\": [ \"root\", \"0penBmc\" ] }" 29``` 30 31- If passing in the username/password as part of the URL, no unique login call 32 is required. The URL format is: 33 34```bash 35 <username>:<password>@<hostname>/<path>... 36``` 37 38For example: 39 40```bash 41 export bmc=xx.xx.xx.xx 42 curl -k -X GET https://root:0penBmc@${bmc}/xyz/openbmc_project/list 43``` 44 45- Token based authentication. 46 47```bash 48 export bmc=xx.xx.xx.xx 49 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 '"'` 50 curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/... 51``` 52 53The third method is recommended. 54 55### Commands 56 57Note: To keep the syntax below common between the phosphor-rest and bmcweb 58implementations as described above, this assumes that if bmcweb is used it is 59using the 'Token based' login method as described above: 60 61```bash 62export bmc=xx.xx.xx.xx 63export 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 '"'` 64curl -k -H "X-Auth-Token: $token" https://$bmc/xyz/openbmc_project/... 65``` 66 67- List and enumerate: 68 69```bash 70 curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/list 71 curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/enumerate 72``` 73 74- List sub-objects: 75 76```bash 77 curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/ 78 curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/state/ 79``` 80 81- Host soft power off: 82 83```bash 84 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 85``` 86 87- Host hard power off: 88 89```bash 90 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 91``` 92 93- Host power on: 94 95```bash 96 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 97``` 98 99- Reboot Host: 100 101```bash 102 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 103``` 104 105- Reboot BMC: 106 107```bash 108 curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data":"xyz.openbmc_project.State.BMC.Transition.Reboot"}' https://${bmc}/xyz/openbmc_project/state/bmc0/attr/RequestedBMCTransition 109``` 110 111- Display logging entries: 112 113```bash 114 curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X GET https://${bmc}/xyz/openbmc_project/logging/entry/enumerate 115``` 116 117- Delete logging entries: 118 119```bash 120 curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X DELETE https://${bmc}/xyz/openbmc_project/logging/entry/<entry_id> 121 curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/logging/action/DeleteAll 122``` 123 124- Delete dump entries: 125 126```bash 127 curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X DELETE https://${bmc}/xyz/openbmc_project/dump/entry/<entry_id> 128 curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/dump/action/DeleteAll 129``` 130 131- Delete images from system: 132 - Delete image: 133 134```bash 135 curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST -d '{"data": []}' https://${bmc}/xyz/openbmc_project/software/<image id>/action/Delete 136``` 137 138- Delete all non-running images: 139 140```bash 141 curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST -d '{"data": []}' https://${bmc}/xyz/openbmc_project/software/action/DeleteAll 142``` 143 144- Clear gard records: 145 146```bash 147 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 148``` 149 150- Control boot source override: 151 - Read current boot source override settings: 152 153```bash 154 curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/control/host0/boot/enumerate 155``` 156 157- Set boot source: 158 159```bash 160 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"}' 161``` 162 163- Set boot mode: 164 165```bash 166 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"}' 167``` 168 169- Set boot type (valid only if host is based on the x86 CPU): 170 171```bash 172 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"}' 173``` 174 175- Set boot source override persistent: 176 177```bash 178 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": "false"}' 179``` 180 181- Enable boot source override: 182 183```bash 184 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"}' 185``` 186 187- Set NTP and Nameserver: 188 189 Examples using public server. 190 - NTP Server: 191 192```bash 193 curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": ["pool.ntp.org"] }' https://${bmc}/xyz/openbmc_project/network/eth0/attr/NTPServers 194``` 195 196- Name Server: 197 198```bash 199 curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": ["time.google.com"] }' https://${bmc}/xyz/openbmc_project/network/eth0/attr/Nameservers 200``` 201 202- Configure time ownership and time sync method: 203 204 The introduction about time setting is here: 205 <https://github.com/openbmc/phosphor-time-manager> 206 207 Note: Starting from OpenBMC 2.6 (with systemd v239), systemd's timedated 208 introduces a new beahvior that it checks the NTP services' status during 209 setting time, instead of checking the NTP setting: 210 211 -When NTP server is set to disabled, and the NTP service is stopping but not 212 stopped, setting time will get an error. 213 214 Before OpenBMC 2.4 (with systemd v236), the above will always succeed. This 215 results in 216 [openbmc/openbmc#3459](https://github.com/openbmc/openbmc/issues/3459), and 217 the related test cases are updated to cooperate with this behavior change. 218 - Read: 219 220```bash 221 curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/xyz/openbmc_project/time/owner/attr/TimeOwner 222 curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/xyz/openbmc_project/time/sync_method/attr/TimeSyncMethod 223``` 224 225- Write: 226 227Time owner: 228 229```bash 230 curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": "xyz.openbmc_project.Time.Owner.Owners.BMC" }' https://${bmc}/xyz/openbmc_project/time/owner/attr/TimeOwner 231 curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": "xyz.openbmc_project.Time.Owner.Owners.Host" }' https://${bmc}/xyz/openbmc_project/time/owner/attr/TimeOwner 232 curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": "xyz.openbmc_project.Time.Owner.Owners.Split" }' https://${bmc}/xyz/openbmc_project/time/owner/attr/TimeOwner 233 curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": "xyz.openbmc_project.Time.Owner.Owners.Both" }' https://${bmc}/xyz/openbmc_project/time/owner/attr/TimeOwner 234``` 235 236Time sync method: 237 238```bash 239 curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": "xyz.openbmc_project.Time.Synchronization.Method.NTP" }' https://${bmc}/xyz/openbmc_project/time/sync_method/attr/TimeSyncMethod 240 curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": "xyz.openbmc_project.Time.Synchronization.Method.Manual" }' https://${bmc}/xyz/openbmc_project/time/sync_method/attr/TimeSyncMethod 241``` 242 243- Power Supply Redundancy: 244 - Read: 245 246```bash 247 curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/xyz/openbmc_project/control/power_supply_redundancy 248``` 249 250- Write (Enable/Disable): 251 252```bash 253 curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/power_supply_redundancy/attr/PowerSupplyRedundancyEnabled -d '{"data": 1}' 254 curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/power_supply_redundancy/attr/PowerSupplyRedundancyEnabled -d '{"data": 0}' 255``` 256 257- Factory Reset: 258 - Factory reset host and BMC software: 259 260```bash 261 curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/software/action/Reset 262``` 263 264- Factory reset network setting: 265 266```bash 267 curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/network/action/Reset 268``` 269 270- Enable field mode: 271 272```bash 273 curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X PUT -d '{"data":1}' https://${bmc}/xyz/openbmc_project/software/attr/FieldModeEnabled 274``` 275 276and then reboot BMC. 277