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* Set boot mode: 127 ``` 128 $ 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/BootMode -d '{"data": "xyz.openbmc_project.Control.Boot.Mode.Modes.Regular"}' 129 ``` 130 131* Set boot source: 132 ``` 133 $ 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/BootSource -d '{"data": "xyz.openbmc_project.Control.Boot.Source.Sources.Default"}' 134 ``` 135 136* Set NTP and Nameserver: 137 138 Examples using public server. 139 - NTP Server: 140 ``` 141 $ 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 142 ``` 143 144 - Name Server: 145 ``` 146 $ 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 147 ``` 148 149* Configure time ownership and time sync method: 150 151 The introduction about time setting is here: 152 https://github.com/openbmc/phosphor-time-manager 153 154 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: 155 156 -When NTP server is set to disabled, and the NTP service is stopping but not stopped, setting time will get an error. 157 158 Before OpenBMC 2.4 (with systemd v236), the above will always succeed. 159 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. 160 161 * Read: 162 ``` 163 $ curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/xyz/openbmc_project/time/owner/attr/TimeOwner 164 $ curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/xyz/openbmc_project/time/sync_method/attr/TimeSyncMethod 165 ``` 166 167 * Write: 168 169 Time owner: 170 ``` 171 $ 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 172 $ 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 173 $ 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 174 $ 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 175 ``` 176 177 Time sync method: 178 ``` 179 $ 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 180 $ 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 181 ``` 182 183* Power Supply Redundancy: 184 185 - Read: 186 ``` 187 $ curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/xyz/openbmc_project/control/power_supply_redundancy 188 ``` 189 190 - Write (Enable/Disable): 191 ``` 192 $ 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}' 193 $ 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}' 194 ``` 195 196* Factory Reset: 197 198 - Factory reset host and BMC software: 199 ``` 200 $ curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/software/action/Reset 201 ``` 202 203 - Factory reset network setting: 204 ``` 205 $ curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/network/action/Reset 206 ``` 207 208 - Enable field mode: 209 ``` 210 $ 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 211 ``` 212 and then reboot BMC. 213