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