xref: /openbmc/docs/REST-cheatsheet.md (revision f31c96df) 
1# OpenBMC REST cheat sheet
2
3This document is intended to provide a set of REST client commands for OpenBMC
4usage. OpenBMC REST is disabled by default in bmcweb. For more information, see
5https://github.com/openbmc/bmcweb/commit/47c9e106e0057dd70133d50e928e48cbc68e709a.
6Most of the functionality previously provided by OpenBMC REST is available in
7Redfish.
8
9## Using CURL commands
10
11### Notes on authentication:
12
13The original REST server, from the phosphor-rest-server repository, uses
14authentication handled by the curl cookie jar files. The bmcweb REST server can
15use the same cookie jar files for read-only REST methods like GET, but requires
16either an authentication token or the username and password passed in as part of
17the URL for non-read-only methods.
18
19Starting with the 2.7 OpenBMC release (August 2019), bmcweb is the default REST
20server. 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
55Note: To keep the syntax below common between the phosphor-rest and bmcweb
56implementations as described above, this assumes that if bmcweb is used it is
57using 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