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