1# OpenBMC REST cheat sheet 2 3This document is intended to provide a set of REST client commands for OpenBMC usage. 4 5## Using CURL commands 6 7### Notes on authentication: 8The original REST server, from the phosphor-rest-server repository, uses 9authentication handled by the curl cookie jar files. The bmcweb REST server 10can use the same cookie jar files for read-only REST methods like GET, but 11requires either an authentication token or the username and password passed in 12as part of the URL for non-read-only methods. 13 14The phosphor-rest server will no longer be the default REST server after the 152.6 OpenBMC release. 16 17### Establish REST connection session 18* Using just the cookie jar files for the phosphor-rest server: 19 ``` 20 $ export bmc=xx.xx.xx.xx 21 $ curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST https://${bmc}/login -d "{\"data\": [ \"root\", \"0penBmc\" ] }" 22 ``` 23* If passing in the username/password as part of the URL, no unique login call 24 is required. The URL format is: 25 ``` 26 <username>:<password>@<hostname>/<path>... 27 ``` 28 For example: 29 ``` 30 $ export bmc=xx.xx.xx.xx 31 curl -k -X GET https://root:0penBmc@${bmc}/xyz/openbmc_project/list 32 ``` 33* Token based authentication. There are two slightly different formats, 34 which return the token differently. In either case, the token is then 35 passed in to future REST calls via the 'X-Auth-Token' or 'Authorization' 36 headers. 37 38 1. Get the authentication token from the header that comes back from the 39 login when using the `data` username/password JSON dictionary and a 40 `-i` argument to show headers: 41 ``` 42 $ export bmc=xx.xx.xx.xx 43 $ curl -i -k -H "Content-Type: application/json" -X POST https://${bmc}/login -d "{\"data\": [ \"root\", \"0penBmc\" ] }" 44 HTTP/1.1 200 OK 45 Set-Cookie: XSRF-TOKEN=4bmZdLP7OXgreUbazXN3; Secure 46 Set-Cookie: SESSION=vnTdgYnvhTnnbirQizrr; Secure; HttpOnly 47 ... 48 49 $ curl -H "X-Auth-Token: vnTdgYnvhTnnbirQizrr" -X POST ... 50 $ curl -H "Authorization: Token vnTdgYnvhTnnbirQizrr" -X POST ... 51 ``` 52 2. Get the authentication token as part of the response when using a JSON 53 dictionary with 'username' and 'password' keys: 54 55 ``` 56 $ export bmc=xx.xx.xx.xx 57 $ curl -k -H "Content-Type: application/json" -X POST https://${bmc}/login -d '{"username" : "root", "password" : "0penBmc"}' 58 { 59 "token": "g47HgLLlZWKLwiyuUwJM" 60 } 61 62 $ curl -H "X-Auth-Token: g47HgLLlZWKLwiyuUwJM -X POST ... 63 $ curl -H "Authorization: Token g47HgLLlZWKLwiyuUwJM -X POST ... 64 ``` 65 66### Commands 67Note: To keep the syntax below common between the phosphor-rest and bmcweb 68 implementations as described above, this assumes that if bmcweb 69 is used it is using the `<username>:<password>@<host>` login method 70 as described above: 71 ``` 72 export bmc=<username>:<password>@xx.xx.xx.xx 73 ``` 74 75* List and enumerate: 76 ``` 77 $ curl -b cjar -k https://${bmc}/xyz/openbmc_project/list 78 $ curl -b cjar -k https://${bmc}/xyz/openbmc_project/enumerate 79 ``` 80 81* List sub-objects: 82 ``` 83 $ curl -b cjar -k https://${bmc}/xyz/openbmc_project/ 84 $ curl -b cjar -k https://${bmc}/xyz/openbmc_project/state/ 85 ``` 86 87* Host soft power off: 88 ``` 89 $ curl -b cjar -k -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 90 ``` 91 92* Host hard power off: 93 ``` 94 $ curl -b cjar -k -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 95 ``` 96 97* Host power on: 98 ``` 99 $ curl -b cjar -k -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 100 ``` 101 102* Reboot Host: 103 ``` 104 $ curl -b cjar -k -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 105 ``` 106 107* Reboot BMC: 108 ``` 109 $ curl -b cjar -k -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 110 ``` 111 112* Display logging entries: 113 ``` 114 $ curl -b cjar -k -H "Content-Type: application/json" -X GET https://${bmc}/xyz/openbmc_project/logging/entry/enumerate 115 ``` 116 117* Delete logging entries: 118 ``` 119 $ curl -b cjar -k -H "Content-Type: application/json" -X DELETE https://${bmc}/xyz/openbmc_project/logging/entry/<entry_id> 120 $ curl -b cjar -k -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/logging/action/DeleteAll 121 ``` 122 123* Delete dump entries: 124 ``` 125 $ curl -b cjar -k -H "Content-Type: application/json" -X DELETE https://${bmc}/xyz/openbmc_project/dump/entry/<entry_id> 126 $ curl -b cjar -k -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/dump/action/DeleteAll 127 ``` 128 129* Delete images from system: 130 131 - Delete image: 132 ``` 133 $ curl -b cjar -k -H "Content-Type: application/json" -X POST -d '{"data": []}' https://${bmc}/xyz/openbmc_project/software/<image id>/action/Delete 134 ``` 135 136 - Delete all non-running images: 137 ``` 138 $ curl -b cjar -k -H "Content-Type: application/json" -X POST -d '{"data": []}' https://${bmc}/xyz/openbmc_project/software/action/DeleteAll 139 ``` 140 141* Clear gard records: 142 ``` 143 $ curl -b cjar -k -H "Content-Type: application/json" -X POST -d '{"data":[]}' https://${bmc}/org/open_power/control/gard/action/Reset 144 ``` 145 146* Set boot mode: 147 ``` 148 $ curl -b cjar -k -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/one_time/attr/BootMode -d '{"data": "xy.openbmc_project.Control.Boot.Mode.Modes.Regular"}' 149 ``` 150 151* Set boot source: 152 ``` 153 $ curl -b cjar -k -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"} 154 ``` 155 156* Set NTP and Nameserver: 157 158 Examples using public server. 159 - NTP Server: 160 ``` 161 $ curl -b cjar -k -H "Content-Type: application/json" -X PUT -d '{"data": ["pool.ntp.org"] }' https://${bmc}/xyz/openbmc_project/network/eth0/attr/NTPServers 162 ``` 163 164 - Name Server: 165 ``` 166 $ curl -b cjar -k -H "Content-Type: application/json" -X PUT -d '{"data": ["time.google.com"] }' https://${bmc}/xyz/openbmc_project/network/eth0/attr/Nameservers 167 ``` 168 169* Configure time ownership and time sync method: 170 171 - Read: 172 ``` 173 $ curl -b cjar -k -X GET https://${bmc}/xyz/openbmc_project/time/owner/attr/TimeOwner 174 $ curl -b cjar -k -X GET https://${bmc}/xyz/openbmc_project/time/sync_method/attr/TimeSyncMethod 175 ``` 176 - Write: 177 ``` 178 $ curl -b cjar -k -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 179 $ curl -b cjar -k -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 180 181 $ curl -b cjar -k -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 182 $ curl -b cjar -k -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 183 $ curl -b cjar -k -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 184 $ curl -b cjar -k -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 185 ``` 186 187* Power Supply Redundancy: 188 189 - Read: 190 ``` 191 $ curl -b cjar -k -H "Content-Type: application/json" -X POST https://${bmc}/xyz/openbmc_project/sensors/chassis/PowerSupplyRedundancy/action/getValue -d '{"data": []}' 192 ``` 193 194 or 195 196 ``` 197 $ curl -b cjar -k -X GET https://${bmc}/xyz/openbmc_project/control/power_supply_redundancy 198 ``` 199 200 - Write (Enable/Disable): 201 ``` 202 $ curl -b cjar -k -H "Content-Type: application/json" -X POST https://${bmc}/xyz/openbmc_project/sensors/chassis/PowerSupplyRedundancy/action/setValue -d '{"data": ["Enabled"]}' 203 204 $ curl -b cjar -k -H "Content-Type: application/json" -X POST https://${bmc}/xyz/openbmc_project/sensors/chassis/PowerSupplyRedundancy/action/setValue -d '{"data": ["Disabled"]}' 205 ``` 206 or 207 208 ``` 209 $ curl -b cjar -k -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/power_supply_redundancy/attr/PowerSupplyRedundancyEnabled -d '{"data": 1}' 210 $ curl -b cjar -k -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/power_supply_redundancy/attr/PowerSupplyRedundancyEnabled -d '{"data": 0}' 211 ``` 212 213* Update "root" password: 214 215 - Change password from "OpenBmc" to "abc123": 216 ``` 217 $ curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST https://${bmc}/login -d "{\"data\": [ \"root\", \"0penBmc\" ] }" 218 $ curl -b cjar -k -H "Content-Type: application/json" -d "{\"data\": [\"abc123\"] }" -X POST https://${bmc}/xyz/openbmc_project/user/root/action/SetPassword 219 ``` 220 221* Factory Reset: 222 223 - Factory reset host and BMC software: 224 ``` 225 $ curl -b cjar -k -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/software/action/Reset 226 ``` 227 228 - Factory reset network setting: 229 ``` 230 $ curl -b cjar -k -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/network/action/Reset 231 ``` 232 233 - Enable field mode: 234 ``` 235 $ curl -b cjar -k -H 'Content-Type: application/json' -X PUT -d '{"data":1}' https://${bmc}/xyz/openbmc_project/software/attr/FieldModeEnabled 236 ``` 237 238 and then reboot BMC. 239