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 133 - Delete image: 134 135```bash 136 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 137``` 138 139- Delete all non-running images: 140 141```bash 142 curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST -d '{"data": []}' https://${bmc}/xyz/openbmc_project/software/action/DeleteAll 143``` 144 145- Clear gard records: 146 147```bash 148 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 149``` 150 151- Control boot source override: 152 153 - Read current boot source override settings: 154 155```bash 156 curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/control/host0/boot/enumerate 157``` 158 159- Set boot source: 160 161```bash 162 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"}' 163``` 164 165- Set boot mode: 166 167```bash 168 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"}' 169``` 170 171- Set boot type (valid only if host is based on the x86 CPU): 172 173```bash 174 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"}' 175``` 176 177- Set boot source override persistent: 178 179```bash 180 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"}' 181``` 182 183- Enable boot source override: 184 185```bash 186 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"}' 187``` 188 189- Set NTP and Nameserver: 190 191 Examples using public server. 192 193 - NTP Server: 194 195```bash 196 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 197``` 198 199- Name Server: 200 201```bash 202 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 203``` 204 205- Configure time ownership and time sync method: 206 207 The introduction about time setting is here: 208 <https://github.com/openbmc/phosphor-time-manager> 209 210 Note: Starting from OpenBMC 2.6 (with systemd v239), systemd's timedated 211 introduces a new beahvior that it checks the NTP services' status during 212 setting time, instead of checking the NTP setting: 213 214 -When NTP server is set to disabled, and the NTP service is stopping but not 215 stopped, setting time will get an error. 216 217 Before OpenBMC 2.4 (with systemd v236), the above will always succeed. This 218 results in 219 [openbmc/openbmc#3459](https://github.com/openbmc/openbmc/issues/3459), and 220 the related test cases are updated to cooperate with this behavior change. 221 222 - Read: 223 224```bash 225 curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/xyz/openbmc_project/time/owner/attr/TimeOwner 226 curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/xyz/openbmc_project/time/sync_method/attr/TimeSyncMethod 227``` 228 229- Write: 230 231Time owner: 232 233```bash 234 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 235 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 236 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 237 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 238``` 239 240Time sync method: 241 242```bash 243 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 244 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 245``` 246 247- Power Supply Redundancy: 248 249 - Read: 250 251```bash 252 curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/xyz/openbmc_project/control/power_supply_redundancy 253``` 254 255- Write (Enable/Disable): 256 257```bash 258 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}' 259 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}' 260``` 261 262- Factory Reset: 263 264 - Factory reset host and BMC software: 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/software/action/Reset 268``` 269 270- Factory reset network setting: 271 272```bash 273 curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/network/action/Reset 274``` 275 276- Enable field mode: 277 278```bash 279 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 280``` 281 282and then reboot BMC. 283