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