Optimize REDFISH and REST documents
Optimized several documents about REST and REDFISH.
Add new command and fix out-of-date commands.
Tested on fp5280g2 that all commands are working on openbmc version
2.8.0-dev-434-g48f8ce5a5-dirty.
Signed-off-by: Xiaochao Ma <maxiaochao@inspur.com>
Change-Id: Ibbf1857cef327e57cceb5ac9f206ddf10601cb42
diff --git a/REDFISH-cheatsheet.md b/REDFISH-cheatsheet.md
index f3b11a6..0528eba 100644
--- a/REDFISH-cheatsheet.md
+++ b/REDFISH-cheatsheet.md
@@ -1,85 +1,92 @@
-# OpenBMC Redfish cheat sheet
+# Redfish cheat sheet
+This document is intended to provide a set of [Redfish][1] client commands for OpenBMC usage.
+(Using CURL commands)
-This document is intended to provide a set of [Redfish][1] client
-commands for OpenBMC usage.
-
-## Using CURL commands
-* Query Root
+## Query Root
+```
+$ export bmc=xx.xx.xx.xx
+$ curl -b cjar -k https://${bmc}/redfish/v1
+```
+## Establish Redfish connection session
+- Method 1
```
$ export bmc=xx.xx.xx.xx
- $ curl -b cjar -k https://${bmc}/redfish/v1
+ $ curl --insecure -X POST -D headers.txt https://${bmc}/redfish/v1/SessionService/Sessions -d '{"UserName":"root", "Password":"0penBmc"}'
+ ```
+ A file, headers.txt, will be created. Find the `"X-Auth-Token"`
+ in that file. Save it away in an env variable like so:
+
+ ```
+ export bmc_token=<token>
+ ```
+- Method 2
+ ```
+ $ export bmc=xx.xx.xx.xx
+ $ 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 '"'`
+ $ curl -k -H "X-Auth-Token: $token" https://${bmc}/redfish/v1/...
+ ```
+ Note: Method 2 is used in this document.
+## View Redfish Objects
+```
+$ curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/redfish/v1/Chassis
+$ curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/redfish/v1/Managers
+$ curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/redfish/v1/Systems
+```
+## Host power
+- Host soft power off:
+ ```
+ $ curl -k -H "X-Auth-Token: $token" -X POST https://${bmc}/redfish/v1/Systems/system/Actions/ComputerSystem.Reset -d '{"ResetType": "GracefulShutdown"}'
+ ```
+- Host hard power off:
+ ```
+ $ curl -k -H "X-Auth-Token: $token" -X POST https://${bmc}/redfish/v1/Systems/system/Actions/ComputerSystem.Reset -d '{"ResetType": "ForceOff"}'
+ ```
+- Host power on:
+ ```
+ $ curl -k -H "X-Auth-Token: $token" -X POST https://${bmc}/redfish/v1/Systems/system/Actions/ComputerSystem.Reset -d '{"ResetType": "On"}'
+ ```
+- Reboot Host:
+ ```
+ $ curl -k -H "X-Auth-Token: $token" -X POST https://${bmc}/redfish/v1/Systems/system/Actions/ComputerSystem.Reset -d '{"ResetType": "GracefulRestart"}'
+ ```
+## Log entry
+- Display logging entries:
+ ```
+ $ curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/redfish/v1/Systems/system/LogServices/EventLog/Entries
+ ```
+- Delete logging entries:
+ ```
+ $ curl -k -H "X-Auth-Token: $token" -X POST https://${bmc}/redfish/v1/Systems/system/LogServices/EventLog/Actions/LogService.Reset
+ ```
+## Firmware ApplyTime:
+ ```
+$ curl -k -H "X-Auth-Token: $token" -X PATCH -d '{ "ApplyTime":"Immediate"}' https://${bmc}/redfish/v1/UpdateService
```
-* Establish Redfish connection session:
- ```
- $ export bmc=xx.xx.xx.xx
- $ curl --insecure -X POST -D headers.txt https://${bmc}/redfish/v1/SessionService/Sessions -d '{"UserName":"root", "Password":"0penBmc"}'
- ```
- A file, headers.txt, will be created. Find the "X-Auth-Token"
- in that file. Save it away in an env variable like so:
- ```
- export bmc_token=<token>
- ```
+or
-* View Redfish Objects
- ```
- $ curl -k -H "X-Auth-Token: $bmc_token" -X GET https://${bmc}/redfish/v1/Chassis
- $ curl -k -H "X-Auth-Token: $bmc_token" -X GET https://${bmc}/redfish/v1/Managers
- $ curl -k -H "X-Auth-Token: $bmc_token" -X GET https://${bmc}/redfish/v1/Systems
- ```
+```
+$ curl -k -H "X-Auth-Token: $token" -X PATCH -d '{ "ApplyTime":"OnReset"}' https://${bmc}/redfish/v1/UpdateService
+```
+## Firmware update
+- Firmware update:
+ Note the `<image file path>` must be a tarball.
-* Host soft power off:
- ```
- $ curl -k -H "X-Auth-Token: $bmc_token" -X POST https://${bmc}/redfish/v1/Systems/system/Actions/ComputerSystem.Reset -d '{"ResetType": "GracefulShutdown"}'
- ```
+ ```
+ $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/octet-stream" -X POST -T <image file path> https://${bmc}/redfish/v1/UpdateService
+ ```
+- TFTP Firmware update using TransferProtocol:
+ Note: The `<image file path>` contains the address of the TFTP service: `xx.xx.xx.xx/obmc-phosphor-xxxxx-xxxxxxxxx.static.mtd.tar`
-* Host hard power off:
- ```
- $ curl -k -H "X-Auth-Token: $bmc_token" -X POST https://${bmc}/redfish/v1/Systems/system/Actions/ComputerSystem.Reset -d '{"ResetType": "ForceOff"}'
- ```
-
-* Host power on:
- ```
- $ curl -k -H "X-Auth-Token: $bmc_token" -X POST https://${bmc}/redfish/v1/Systems/system/Actions/ComputerSystem.Reset -d '{"ResetType": "On"}'
- ```
-
-* Reboot Host:
- ```
- $ curl -k -H "X-Auth-Token: $bmc_token" -X POST https://${bmc}/redfish/v1/Systems/system/Actions/ComputerSystem.Reset -d '{"ResetType": "GracefulRestart"}'
- ```
-
-* Display logging entries:
- ```
- $ curl -k -H "X-Auth-Token: $bmc_token" -X GET https://${bmc}/redfish/v1/Systems/system/LogServices/EventLog/Entries
- ```
-
-* Delete logging entries:
- ```
- $ curl -k -H "X-Auth-Token: $bmc_token" -X POST https://${bmc}/redfish/v1/Systems/system/LogServices/EventLog/Actions/LogService.Reset
- ```
-
-* Firmware ApplyTime:
- ```
- $ curl -k -H "X-Auth-Token: $bmc_token" -X PATCH -d '{ "ApplyTime":"Immediate"}' https://${bmc}/redfish/v1/UpdateService
- ```
-
- ```
- $ curl -k -H "X-Auth-Token: $bmc_token" -X PATCH -d '{ "ApplyTime":"OnReset"}' https://${bmc}/redfish/v1/UpdateService
- ```
-
-* Firmware update:
- ```
- $ curl -k -H "X-Auth-Token: $bmc_token" -H "Content-Type: application/octet-stream" -X POST -T <image file path> https://${bmc}/redfish/v1/UpdateService
- ```
-
-* TFTP Firmware update using TransferProtocol:
- ```
- curl -k -H "X-Auth-Token: $bmc_token" -X POST https://${bmc}/redfish/v1/UpdateService/Actions/UpdateService.SimpleUpdate -d '{"TransferProtocol":"TFTP","ImageURI":"<image file path>"}'
- ```
-
-* TFTP Firmware update with protocol in ImageURI:
- ```
- curl -k -H "X-Auth-Token: $bmc_token" -X POST https://${bmc}/redfish/v1/UpdateService/Actions/UpdateService.SimpleUpdate -d '{"ImageURI":"tftp://<image file path>"}'
- ```
-
-[1]: https://www.dmtf.org/standards/redfish
+ ```
+ $ curl -k -H "X-Auth-Token: $token" -X POST https://${bmc}/redfish/v1/UpdateService/Actions/UpdateService.SimpleUpdate -d '{"TransferProtocol":"TFTP","ImageURI":"<image file path>"}'
+ ```
+- TFTP Firmware update with protocol in ImageURI:
+ ```
+ $ curl -k -H "X-Auth-Token: $token" -X POST https://${bmc}/redfish/v1/UpdateService/Actions/UpdateService.SimpleUpdate -d '{"ImageURI":"tftp://<image file path>"}'
+ ```
+## Update "root" password
+Change password to "0penBmc1":
+```
+$ curl -k -H "X-Auth-Token: $token" -X PATCH -d '{"Password": "0penBmc1"}' https://${bmc}/redfish/v1/AccountService/Accounts/root
+```
\ No newline at end of file
diff --git a/REST-cheatsheet.md b/REST-cheatsheet.md
index 1f9e1a5..ccf6b89 100644
--- a/REST-cheatsheet.md
+++ b/REST-cheatsheet.md
@@ -16,223 +16,210 @@
### Establish REST connection session
* Using just the cookie jar files for the phosphor-rest server:
- ```
+ ```
$ export bmc=xx.xx.xx.xx
$ curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST https://${bmc}/login -d "{\"data\": [ \"root\", \"0penBmc\" ] }"
- ```
+ ```
* If passing in the username/password as part of the URL, no unique login call
is required. The URL format is:
- ```
- <username>:<password>@<hostname>/<path>...
- ```
+
+ ```
+ <username>:<password>@<hostname>/<path>...
+ ```
For example:
- ```
- $ export bmc=xx.xx.xx.xx
- curl -k -X GET https://root:0penBmc@${bmc}/xyz/openbmc_project/list
- ```
-* Token based authentication. There are two slightly different formats,
- which return the token differently. In either case, the token is then
- passed in to future REST calls via the 'X-Auth-Token' or 'Authorization'
- headers.
-
- 1. Get the authentication token from the header that comes back from the
- login when using the `data` username/password JSON dictionary and a
- `-i` argument to show headers:
- ```
- $ export bmc=xx.xx.xx.xx
- $ curl -i -k -H "Content-Type: application/json" -X POST https://${bmc}/login -d "{\"data\": [ \"root\", \"0penBmc\" ] }"
- HTTP/1.1 200 OK
- Set-Cookie: XSRF-TOKEN=4bmZdLP7OXgreUbazXN3; Secure
- Set-Cookie: SESSION=vnTdgYnvhTnnbirQizrr; Secure; HttpOnly
- ...
-
- $ curl -H "X-Auth-Token: vnTdgYnvhTnnbirQizrr" -X POST ...
- $ curl -H "Authorization: Token vnTdgYnvhTnnbirQizrr" -X POST ...
- ```
- 2. Get the authentication token as part of the response when using a JSON
- dictionary with 'username' and 'password' keys:
+ ```
+ $ export bmc=xx.xx.xx.xx
+ $ curl -k -X GET https://root:0penBmc@${bmc}/xyz/openbmc_project/list
+ ```
+* Token based authentication.
```
- $ export bmc=xx.xx.xx.xx
- $ curl -k -H "Content-Type: application/json" -X POST https://${bmc}/login -d '{"username" : "root", "password" : "0penBmc"}'
- {
- "token": "g47HgLLlZWKLwiyuUwJM"
- }
+ $ export bmc=xx.xx.xx.xx
+ $ 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 '"'`
+ $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/...
+ ```
- $ curl -H "X-Auth-Token: g47HgLLlZWKLwiyuUwJM -X POST ...
- $ curl -H "Authorization: Token g47HgLLlZWKLwiyuUwJM -X POST ...
- ```
+ The third method is recommended.
### Commands
Note: To keep the syntax below common between the phosphor-rest and bmcweb
implementations as described above, this assumes that if bmcweb
- is used it is using the `<username>:<password>@<host>` login method
- as described above:
+ is used it is using the 'Token based' login method as described above:
+
```
- export bmc=<username>:<password>@xx.xx.xx.xx
+ $ export bmc=xx.xx.xx.xx
+ $ 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 '"'`
+ $ curl -k -H "X-Auth-Token: $token" https://$bmc/xyz/openbmc_project/...
```
* List and enumerate:
- ```
- $ curl -b cjar -k https://${bmc}/xyz/openbmc_project/list
- $ curl -b cjar -k https://${bmc}/xyz/openbmc_project/enumerate
- ```
+ ```
+ $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/list
+ $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/enumerate
+ ```
* List sub-objects:
- ```
- $ curl -b cjar -k https://${bmc}/xyz/openbmc_project/
- $ curl -b cjar -k https://${bmc}/xyz/openbmc_project/state/
- ```
+ ```
+ $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/
+ $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/state/
+ ```
* Host soft power off:
- ```
- $ 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
- ```
+ ```
+ $ 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
+ ```
* Host hard power off:
- ```
- $ 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
- ```
+ ```
+ $ 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
+ ```
* Host power on:
- ```
- $ 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
- ```
+ ```
+ $ 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
+ ```
* Reboot Host:
- ```
- $ 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
- ```
+ ```
+ $ 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
+ ```
* Reboot BMC:
- ```
- $ 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
- ```
+ ```
+ $ 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
+ ```
* Display logging entries:
- ```
- $ curl -b cjar -k -H "Content-Type: application/json" -X GET https://${bmc}/xyz/openbmc_project/logging/entry/enumerate
- ```
+ ```
+ $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X GET https://${bmc}/xyz/openbmc_project/logging/entry/enumerate
+ ```
* Delete logging entries:
- ```
- $ curl -b cjar -k -H "Content-Type: application/json" -X DELETE https://${bmc}/xyz/openbmc_project/logging/entry/<entry_id>
- $ curl -b cjar -k -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/logging/action/DeleteAll
- ```
+ ```
+ $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X DELETE https://${bmc}/xyz/openbmc_project/logging/entry/<entry_id>
+ $ curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/logging/action/DeleteAll
+ ```
* Delete dump entries:
- ```
- $ curl -b cjar -k -H "Content-Type: application/json" -X DELETE https://${bmc}/xyz/openbmc_project/dump/entry/<entry_id>
- $ curl -b cjar -k -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/dump/action/DeleteAll
- ```
+ ```
+ $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X DELETE https://${bmc}/xyz/openbmc_project/dump/entry/<entry_id>
+ $ curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/dump/action/DeleteAll
+ ```
* Delete images from system:
- Delete image:
- ```
- $ curl -b cjar -k -H "Content-Type: application/json" -X POST -d '{"data": []}' https://${bmc}/xyz/openbmc_project/software/<image id>/action/Delete
- ```
+ ```
+ $ 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
+ ```
- Delete all non-running images:
- ```
- $ curl -b cjar -k -H "Content-Type: application/json" -X POST -d '{"data": []}' https://${bmc}/xyz/openbmc_project/software/action/DeleteAll
- ```
+ ```
+ $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST -d '{"data": []}' https://${bmc}/xyz/openbmc_project/software/action/DeleteAll
+ ```
* Clear gard records:
- ```
- $ curl -b cjar -k -H "Content-Type: application/json" -X POST -d '{"data":[]}' https://${bmc}/org/open_power/control/gard/action/Reset
- ```
+ ```
+ $ 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
+ ```
* Set boot mode:
- ```
- $ 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": "xyz.openbmc_project.Control.Boot.Mode.Modes.Regular"}'
- ```
+ ```
+ $ 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"}'
+ ```
* Set boot source:
- ```
- $ 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"}
- ```
+ ```
+ $ 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"}'
+ ```
* Set NTP and Nameserver:
Examples using public server.
- NTP Server:
- ```
- $ 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
- ```
+ ```
+ $ 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
+ ```
- Name Server:
- ```
- $ 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
- ```
+ ```
+ $ 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
+ ```
* Configure time ownership and time sync method:
- - Read:
- ```
- $ curl -b cjar -k -X GET https://${bmc}/xyz/openbmc_project/time/owner/attr/TimeOwner
- $ curl -b cjar -k -X GET https://${bmc}/xyz/openbmc_project/time/sync_method/attr/TimeSyncMethod
- ```
- - Write:
- ```
- $ 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
- $ 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
+ The introduction about time setting is here:
+ https://github.com/openbmc/phosphor-time-manager
- $ 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
- $ 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
- $ 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
- $ 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
- ```
+ 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:
+
+ -When NTP server is set to disabled, and the NTP service is stopping but not stopped, setting time will get an error.
+
+ Before OpenBMC 2.4 (with systemd v236), the above will always succeed.
+ 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.
+
+ * Read:
+ ```
+ $ curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/xyz/openbmc_project/time/owner/attr/TimeOwner
+ $ curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/xyz/openbmc_project/time/sync_method/attr/TimeSyncMethod
+ ```
+
+ * Write:
+
+ Time owner:
+ ```
+ $ 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
+ $ 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
+ $ 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
+ $ 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
+ ```
+
+ Time sync method:
+ ```
+ $ 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
+ $ 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
+ ```
* Power Supply Redundancy:
- Read:
- ```
- $ curl -b cjar -k -H "Content-Type: application/json" -X POST https://${bmc}/xyz/openbmc_project/sensors/chassis/PowerSupplyRedundancy/action/getValue -d '{"data": []}'
- ```
+ ```
+ $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST https://${bmc}/xyz/openbmc_project/sensors/chassis/PowerSupplyRedundancy/action/getValue -d '{"data": []}'
+ ```
or
- ```
- $ curl -b cjar -k -X GET https://${bmc}/xyz/openbmc_project/control/power_supply_redundancy
- ```
+ ```
+ $ curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/xyz/openbmc_project/control/power_supply_redundancy
+ ```
- Write (Enable/Disable):
- ```
- $ curl -b cjar -k -H "Content-Type: application/json" -X POST https://${bmc}/xyz/openbmc_project/sensors/chassis/PowerSupplyRedundancy/action/setValue -d '{"data": ["Enabled"]}'
+ ```
+ $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST https://${bmc}/xyz/openbmc_project/sensors/chassis/PowerSupplyRedundancy/action/setValue -d '{"data": ["Enabled"]}'
+ $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST https://${bmc}/xyz/openbmc_project/sensors/chassis/PowerSupplyRedundancy/action/setValue -d '{"data": ["Disabled"]}'
+ ```
- $ curl -b cjar -k -H "Content-Type: application/json" -X POST https://${bmc}/xyz/openbmc_project/sensors/chassis/PowerSupplyRedundancy/action/setValue -d '{"data": ["Disabled"]}'
- ```
or
- ```
- $ 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}'
- $ 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}'
- ```
-
-* Update "root" password:
-
- - Change password from "OpenBmc" to "abc123":
- ```
- $ curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST https://${bmc}/login -d "{\"data\": [ \"root\", \"0penBmc\" ] }"
- $ curl -b cjar -k -H "Content-Type: application/json" -d "{\"data\": [\"abc123\"] }" -X POST https://${bmc}/xyz/openbmc_project/user/root/action/SetPassword
- ```
+ ```
+ $ 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}'
+ $ 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}'
+ ```
* Factory Reset:
- Factory reset host and BMC software:
- ```
- $ curl -b cjar -k -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/software/action/Reset
- ```
+ ```
+ $ curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/software/action/Reset
+ ```
- Factory reset network setting:
- ```
- $ curl -b cjar -k -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/network/action/Reset
- ```
+ ```
+ $ curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/network/action/Reset
+ ```
- Enable field mode:
- ```
- $ curl -b cjar -k -H 'Content-Type: application/json' -X PUT -d '{"data":1}' https://${bmc}/xyz/openbmc_project/software/attr/FieldModeEnabled
- ```
-
- and then reboot BMC.
+ ```
+ $ 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
+ ```
+ and then reboot BMC.
\ No newline at end of file
diff --git a/host-management.md b/host-management.md
index 08a6cc5..6bc6a2f 100644
--- a/host-management.md
+++ b/host-management.md
@@ -1,11 +1,21 @@
-Host Management with OpenBMC
-============================
+# Host Management with OpenBMC
This document describes the host-management interfaces of the OpenBMC object
structure, accessible over REST.
-Inventory
----------
+Note: Authentication
+
+See the details on authentication at [REST-cheatsheet](https://github.com/openbmc/docs/blob/master/REST-cheatsheet.md#establish-rest-connection-session).
+
+This document uses token based authentication method:
+
+```
+$ export bmc=xx.xx.xx.xx
+$ 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 '"'`
+$ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/...
+```
+
+## Inventory
The system inventory structure is under the `/xyz/openbmc_project/inventory` hierarchy.
@@ -15,7 +25,7 @@
contains one chassis, a motherboard, and a CPU on the motherboard, then the
path to that inventory item would be:
- inventory/system/chassis0/motherboard0/cpu0
+ `inventory/system/chassis0/motherboard0/cpu0`
The properties associated with an inventory item are specific to that item.
Some common properties are:
@@ -28,14 +38,13 @@
structure to be accessed. For example, to enumerate all inventory items and
their properties:
- curl -b cjar -k https://${bmc}/xyz/openbmc_project/inventory/enumerate
+ $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/inventory/enumerate
To list the properties of one item:
- curl -b cjar -k https://${bmc}/xyz/openbmc_project/inventory/system/chassis/motherboard
+ $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/inventory/system/chassis/motherboard
-Sensors
--------
+## Sensors
The system sensor structure is under the `/xyz/openbmc_project/sensors`
hierarchy.
@@ -65,40 +74,42 @@
A temperature sensor might look like:
- curl -b cjar -k https://${bmc}/xyz/openbmc_project/sensors/temperature/pcie
+ $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/sensors/temperature/ocp_zone
{
"data": {
- "CriticalAlarmHigh": 0,
- "CriticalAlarmLow": 0,
- "CriticalHigh": 70000,
+ "CriticalAlarmHigh": false,
+ "CriticalAlarmLow": false,
+ "CriticalHigh": 65000,
"CriticalLow": 0,
+ "Functional": true,
+ "MaxValue": 0,
+ "MinValue": 0,
"Scale": -3,
"Unit": "xyz.openbmc_project.Sensor.Value.Unit.DegreesC",
- "Value": 28187,
- "WarningAlarmHigh": 0,
- "WarningAlarmLow": 0,
- "WarningHigh": 60000,
+ "Value": 34625,
+ "WarningAlarmHigh": false,
+ "WarningAlarmLow": false,
+ "WarningHigh": 63000,
"WarningLow": 0
},
"message": "200 OK",
"status": "ok"
}
-Note the value of this sensor is 28.187C (28187 * 10^-3).
+Note the value of this sensor is 34.625C (34625 * 10^-3).
Unlike IPMI, there are no "functional" sensors in OpenBMC; functional states are
represented in the inventory.
To enumerate all sensors in the system:
- curl -b cjar -k https://${bmc}/xyz/openbmc_project/sensors/enumerate
+ $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/sensors/enumerate
List properties of one inventory item:
- curl -b cjar -k https://${bmc}/xyz/openbmc_project/sensors/temperature/ambient
+ $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/sensors/temperature/outlet
-Event Logs
-----------
+## Event Logs
The event log structure is under the `/xyz/openbmc_project/logging/entry`
hierarchy. Each event is a separate object under this structure, referenced by
@@ -114,11 +125,11 @@
* `Resolved` : Indicates whether the event has been resolved.
* `Severity`: The level of problem ("Info", "Error", etc.).
* `Timestamp`: The date of the event log in epoch time.
- * `associations`: A URI to the failing inventory part.
+ * `Associations`: A URI to the failing inventory part.
To list all reported event logs:
- $ curl -b cjar -k https://${bmc}/xyz/openbmc_project/logging/entry/
+ $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/logging/entry
{
"data": [
"/xyz/openbmc_project/logging/entry/3",
@@ -135,44 +146,34 @@
To read a specific event log:
- $ curl -b cjar -k https://${bmc}/xyz/openbmc_project/logging/entry/1
+ $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/logging/entry/1
{
"data": {
"AdditionalData": [
- "CALLOUT_INVENTORY_PATH=/xyz/openbmc_project/inventory/system/chassis/powersupply0",
- "_PID=1136"
+ "_PID=183"
],
"Id": 1,
- "Message": "xyz.openbmc_project.Inventory.Error.NotPresent",
- "Resolved": 0,
+ "Message": "xyz.openbmc_project.Common.Error.InternalFailure",
+ "Purpose": "xyz.openbmc_project.Software.Version.VersionPurpose.BMC",
+ "Resolved": false,
"Severity": "xyz.openbmc_project.Logging.Entry.Level.Error",
- "Timestamp": 1512154612660,
- "associations": [
- [
- "callout",
- "fault",
- "/xyz/openbmc_project/inventory/system/chassis/powersupply0"
- ]
- ]
+ "Timestamp": 1563191362822,
+ "Version": "2.8.0-dev-132-gd1c1b74-dirty",
+ "associations": []
},
"message": "200 OK",
"status": "ok"
}
-To delete an event log (log 1 in this example), call the `delete` method on the event:
+To delete an event log (log 1 in this example), call the `Delete` method on the event:
- curl -b cjar -k -H "Content-Type: application/json" -X POST \
- -d '{"data" : []}' \
- https://${bmc}/xyz/openbmc_project/logging/entry/1/action/Delete
+ $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST -d '{"data" : []}' https://${bmc}/xyz/openbmc_project/logging/entry/1/action/Delete
To clear all event logs, call the top-level `DeleteAll` method:
- curl -b cjar -k -H "Content-Type: application/json" -X POST \
- -d '{"data" : []}' \
- https://${bmc}/xyz/openbmc_project/logging/action/DeleteAll
+ $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST -d '{"data" : []}' https://${bmc}/xyz/openbmc_project/logging/action/DeleteAll
-Host Boot Options
------------------
+## Host Boot Options
With OpenBMC, the Host boot options are stored as D-Bus properties under the
`control/host0/boot` path. Properties include
@@ -180,9 +181,19 @@
and
[`BootSource`](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Control/Boot/Source.interface.yaml).
+ * Set boot mode:
-Host State Control
-------------------
+ ```
+ $ 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"}'
+ ```
+
+ * Set boot source:
+
+ ```
+ $ 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"}'
+ ```
+
+## Host State Control
The host can be controlled through the `host` object. The object implements a
number of actions including power on and power off. These correspond to the IPMI
@@ -191,41 +202,32 @@
Assuming you have logged in, the following will power on the host:
```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X PUT \
- -d '{"data": "xyz.openbmc_project.State.Host.Transition.On"}' \
- https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
+$ 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
```
To power off the host:
```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X PUT \
- -d '{"data": "xyz.openbmc_project.State.Host.Transition.Off"}' \
- https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
+$ 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
```
To issue a hard power off (accomplished by powering off the chassis):
```
-curl -c cjar -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
+$ 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
```
To reboot the host:
```
-curl -c cjar -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
+$ 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
```
More information about Host State Management can be found here:
https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/xyz/openbmc_project/State
-Host Clear GARD
----------------
+## Host Clear GARD
On OpenPOWER systems, the host maintains a record of bad or non-working
components on the GARD partition. This record is referenced by the host on
@@ -245,13 +247,12 @@
* Method 2: Using the REST API:
```
- curl -b cjar -k -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/org/open_power/control/gard/action/Reset
+ $ 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
```
Implementation: https://github.com/openbmc/openpower-pnor-code-mgmt
-Host Watchdog
--------------
+## Host Watchdog
The host watchdog service is responsible for ensuring the host starts and boots
within a reasonable time. On host start, the watchdog is started and it is
diff --git a/redfish-logging-in-bmcweb.md b/redfish-logging-in-bmcweb.md
index a3b7f48..a339e54 100644
--- a/redfish-logging-in-bmcweb.md
+++ b/redfish-logging-in-bmcweb.md
@@ -22,18 +22,18 @@
If an appropriate message exists, note the
1. Title of the Message Object (required as the MessageKey in the MessageId).
-1. Args (notated as "%x") in the "Message" field
+2. Args (notated as "%x") in the "Message" field
(required for the MessageArgs).
If an appropriate message does not exist, new messages can be added as follows:
1. Choose a Message Registry for the new message
-1. Choose a MessageKey to use as the title for the new Message entry
-1. Insert a new Message entry (preferably with the title in alphabetical order)
-1. Add a `description` and `resolution`
-1. Set the `severity` to "Critical", "Warning", or "OK"
-1. Define the `message` with any necessary args
-1. Set the `numberOfArgs` and `paramTypes` to match the message args
+2. Choose a MessageKey to use as the title for the new Message entry
+3. Insert a new Message entry (preferably with the title in alphabetical order)
+4. Add a `description` and `resolution`
+5. Set the `severity` to "Critical", "Warning", or "OK"
+6. Define the `message` with any necessary args
+7. Set the `numberOfArgs` and `paramTypes` to match the message args
## Logging Messages
@@ -53,8 +53,8 @@
The journal is the current mechanism used to log Redfish Messages. bmcweb
looks for two fields in the journal metadata:
-* `REDFISH_MESSAGE_ID`: A string holding the MessageId
-* `REDFISH_MESSAGE_ARGS`: A string holding a comma-separated list of args
+- `REDFISH_MESSAGE_ID`: A string holding the MessageId
+- `REDFISH_MESSAGE_ARGS`: A string holding a comma-separated list of args
These fields can be added to a journal entry using either the
`phosphor::logging::entry()` command or directly using the
@@ -67,6 +67,7 @@
The
[Resource Event Message Registry](https://redfish.dmtf.org/registries/ResourceEvent.1.0.0.json)
holds the ResourceCreated message:
+
```json
{
"ResourceCreated": {
@@ -82,13 +83,16 @@
Since there are no parameters, no MessageArgs are required, so this message
can be logged to the journal as follows:
+
```cpp
phosphor::logging::log<log::level>(
"journal text",
phosphor::logging::entry("REDFISH_MESSAGE_ID=%s",
"ResourceEvent.1.0.ResourceCreated"));
```
+
or
+
```cpp
sd_journal_send("MESSAGE=%s", "journal text", "PRIORITY=%i", <LOG_LEVEL>,
"REDFISH_MESSAGE_ID=%s",
@@ -99,6 +103,7 @@
The
[Resource Event Message Registry](https://redfish.dmtf.org/registries/ResourceEvent.1.0.0.json)
holds the ResourceErrorThresholdExceeded message:
+
```json
{
"ResourceErrorThresholdExceeded": {
@@ -127,6 +132,7 @@
The parameters are filled from a comma-separated list of the MessageArgs, so
this message can be logged to the journal as follows:
+
```cpp
phosphor::logging::log<log::level>(
"journal text",
@@ -135,11 +141,13 @@
phosphor::logging::entry("REDFISH_MESSAGE_ARGS=%s,%d",
"Property Name", propertyValue));
```
+
or
+
```cpp
sd_journal_send("MESSAGE=%s", "journal text", "PRIORITY=%i", <LOG_LEVEL>,
"REDFISH_MESSAGE_ID=%s",
"ResourceEvent.1.0.ResourceErrorThresholdExceeded",
"REDFISH_MESSAGE_ARGS=%s,%d", "Property Name",
propertyValue, NULL);
-```
+```
\ No newline at end of file
diff --git a/rest-api.md b/rest-api.md
index fc88310..7c570dc 100644
--- a/rest-api.md
+++ b/rest-api.md
@@ -12,15 +12,14 @@
## Authentication
-See the details on authentication at
-https://github.com/openbmc/docs/blob/master/REST-cheatsheet.md
+See the details on authentication at [REST-cheatsheet](https://github.com/openbmc/docs/blob/master/REST-cheatsheet.md#establish-rest-connection-session).
-This tutorial uses the basic authentication URL encoding, so just pass in the
-user name and password as part of the URL and no separate login/logout commands
-are required:
+This tutorial uses token based authentication method:
```
-export bmc=<username>:<password>@<hostname>
+$ export bmc=xx.xx.xx.xx
+$ 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 '"'`
+$ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/...
```
## HTTP GET operations & URL structure
@@ -31,103 +30,129 @@
- To query the attributes of an object, perform a GET request on the object
name, with no trailing slash. For example:
- $ curl -k https://${bmc}/xyz/openbmc_project/inventory/system
- {
- "data": {
- "AssetTag": "",
- "BuildDate": "",
- "Cached": 0,
- "FieldReplaceable": 0,
- "Manufacturer": "",
- "Model": "0000000000000000",
- "PartNumber": "",
- "Present": 1,
- "PrettyName": "",
- "SerialNumber": "0000000000000000"
- },
- "message": "200 OK",
- "status": "ok"
- }
+ ```
+ $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/inventory/system
+ {
+ "data": {
+ "AssetTag": "",
+ "BuildDate": "",
+ "Cached": true,
+ "FieldReplaceable": true,
+ "Manufacturer": "",
+ "Model": "",
+ "PartNumber": "",
+ "Present": true,
+ "PrettyName": "",
+ "SerialNumber": ""
+ },
+ "message": "200 OK",
+ "status": "ok"
+ }
+ ```
- To query a single attribute, use the `attr/<name>` path. Using the
`system` object from above, we can query just the `Name` value:
- $ curl -k https://${bmc}/xyz/openbmc_project/inventory/system/attr/Model
- {
- "data": "0000000000000000",
- "message": "200 OK",
- "status": "ok"
- }
+ ```
+ $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/inventory/system/attr/Cached
+ {
+ "data": true,
+ "message": "200 OK",
+ "status": "ok"
+ }
+ ```
- When a path has a trailing-slash, the response will list the sub objects of
the URL. For example, using the same object path as above, but adding a
slash:
- $ curl -k https://${bmc}/xyz/openbmc_project/
- {
- "data": [
- "/xyz/openbmc_project/dump",
- "/xyz/openbmc_project/software",
- "/xyz/openbmc_project/control",
- "/xyz/openbmc_project/network",
- "/xyz/openbmc_project/logging",
- "/xyz/openbmc_project/sensors",
- "/xyz/openbmc_project/inventory",
- "/xyz/openbmc_project/user",
- "/xyz/openbmc_project/time",
- "/xyz/openbmc_project/led",
- "/xyz/openbmc_project/state"
+ ```
+ $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/
+ {
+ "data": [
+ "/xyz/openbmc_project/Chassis",
+ "/xyz/openbmc_project/Hiomapd",
+ "/xyz/openbmc_project/Ipmi",
+ "/xyz/openbmc_project/certs",
+ "/xyz/openbmc_project/console",
+ "/xyz/openbmc_project/control",
+ "/xyz/openbmc_project/dump",
+ "/xyz/openbmc_project/events",
+ "/xyz/openbmc_project/inventory",
+ "/xyz/openbmc_project/ipmi",
+ "/xyz/openbmc_project/led",
+ "/xyz/openbmc_project/logging",
+ "/xyz/openbmc_project/network",
+ "/xyz/openbmc_project/object_mapper",
+ "/xyz/openbmc_project/sensors",
+ "/xyz/openbmc_project/software",
+ "/xyz/openbmc_project/state",
+ "/xyz/openbmc_project/time",
+ "/xyz/openbmc_project/user"
+ ],
+ "message": "200 OK",
+ "status": "ok"
+ }
+ ```
- ],
- "message": "200 OK",
- "status": "ok"
- }
-
- This shows that there are 11 children of the `openbmc_project/` object:
- `dump`, `software`, `control`, `network`, `logging`, `sensors`, `inventory`,
- `user`, `time`, `led`, and `state`. This can be used with the base REST URL
- (ie., `http://${bmc}/`), to discover all objects in the hierarchy.
+ This shows that there are 19 children of the `openbmc_project/` object: `dump`, `software`, `control`, `network`, `logging`,etc. This can be used with the base REST URL (ie., `http://${bmc}/`), to discover all objects in the hierarchy.
- Performing the same query with `/list` will list the child objects
*recursively*.
- $ curl -k https://${bmc}/xyz/openbmc_project/network/list
- {
- "data": [
- "/xyz/openbmc_project/network/config",
- "/xyz/openbmc_project/network/eth0",
- "/xyz/openbmc_project/network/eth0/ipv4/3cf9573",
- "/xyz/openbmc_project/network/eth0/ipv6/c354c06",
- "/xyz/openbmc_project/network/host0/intf",
- "/xyz/openbmc_project/network/host0/intf/addr",
- "/xyz/openbmc_project/network/config/dhcp"
- ],
- "message": "200 OK",
- "status": "ok"
- }
+ ```
+ $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/network/list
+ {
+ "data": [
+ "/xyz/openbmc_project/network/config",
+ "/xyz/openbmc_project/network/config/dhcp",
+ "/xyz/openbmc_project/network/eth0",
+ "/xyz/openbmc_project/network/eth0/ipv4",
+ "/xyz/openbmc_project/network/eth0/ipv4/3b9faa36",
+ "/xyz/openbmc_project/network/eth0/ipv6",
+ "/xyz/openbmc_project/network/eth0/ipv6/ff81b6d6",
+ "/xyz/openbmc_project/network/eth1",
+ "/xyz/openbmc_project/network/eth1/ipv4",
+ "/xyz/openbmc_project/network/eth1/ipv4/3b9faa36",
+ "/xyz/openbmc_project/network/eth1/ipv4/66e63348",
+ "/xyz/openbmc_project/network/eth1/ipv6",
+ "/xyz/openbmc_project/network/eth1/ipv6/ff81b6d6",
+ "/xyz/openbmc_project/network/host0",
+ "/xyz/openbmc_project/network/host0/intf",
+ "/xyz/openbmc_project/network/host0/intf/addr",
+ "/xyz/openbmc_project/network/sit0",
+ "/xyz/openbmc_project/network/snmp",
+ "/xyz/openbmc_project/network/snmp/manager"
+ ],
+ "message": "200 OK",
+ "status": "ok"
+ }
+ ```
- Adding `/enumerate` instead of `/list` will also include the attributes of
the listed objects.
- $ curl -k https://${bmc}/xyz/openbmc_project/time/enumerate
- {
- "data": {
- "/xyz/openbmc_project/time/bmc": {
- "Elapsed": 1511205212119165
- },
- "/xyz/openbmc_project/time/host": {
- "Elapsed": 1511205212134372
- },
- "/xyz/openbmc_project/time/owner": {
- "TimeOwner": "xyz.openbmc_project.Time.Owner.Owners.BMC"
- },
- "/xyz/openbmc_project/time/sync_method": {
- "TimeSyncMethod": "xyz.openbmc_project.Time.Synchronization.Method.NTP"
- }
- },
- "message": "200 OK",
- "status": "ok"
- }
+ ```
+ $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/time/enumerate
+ {
+ "data": {
+ "/xyz/openbmc_project/time/bmc": {
+ "Elapsed": 1563209492098739
+ },
+ "/xyz/openbmc_project/time/host": {
+ "Elapsed": 1563209492101678
+ },
+ "/xyz/openbmc_project/time/owner": {
+ "TimeOwner": "xyz.openbmc_project.Time.Owner.Owners.BMC"
+ },
+ "/xyz/openbmc_project/time/sync_method": {
+ "TimeSyncMethod": "xyz.openbmc_project.Time.Synchronization.Method.NTP"
+ }
+ },
+ "message": "200 OK",
+ "status": "ok"
+ }
+ ```
## HTTP PUT operations
@@ -136,32 +161,33 @@
These require a json formatted payload. To get an example of what that looks
like:
- curl -k https://${bmc}/xyz/openbmc_project/state/host0 > host.json
-
- $ cat host.json
- {
- "data": {
- "AttemptsLeft": 0,
- "BootProgress": "xyz.openbmc_project.State.Boot.Progress.ProgressStages.Unspecified",
- "CurrentHostState": "xyz.openbmc_project.State.Host.HostState.Off",
- "OperatingSystemState": "xyz.openbmc_project.State.OperatingSystem.Status.OSStatus.Inactive",
- "RequestedHostTransition": "xyz.openbmc_project.State.Host.Transition.Off"
- },
- "message": "200 OK",
- "status": "ok"
- }
+```
+$ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/state/host0 > host.json
+$ cat host.json
+{
+ "data": {
+ "AttemptsLeft": 3,
+ "BootProgress": "xyz.openbmc_project.State.Boot.Progress.ProgressStages.Unspecified",
+ "CurrentHostState": "xyz.openbmc_project.State.Host.HostState.Off",
+ "OperatingSystemState": "xyz.openbmc_project.State.OperatingSystem.Status.OSStatus.Inactive",
+ "RequestedHostTransition": "xyz.openbmc_project.State.Host.Transition.Off"
+ },
+ "message": "200 OK",
+ "status": "ok"
+}
+```
or
- curl -k \
- https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition > requested_host.json
-
- $ cat requested_host.json
- {
- "data": "xyz.openbmc_project.State.Host.Transition.Off",
- "message": "200 OK",
- "status": "ok"
- }
+```
+$ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition > requested_host.json
+$ cat requested_host.json
+{
+ "data": "xyz.openbmc_project.State.Host.Transition.Off",
+ "message": "200 OK",
+ "status": "ok"
+}
+```
When turning around and sending these as requests, delete the message and status
properties.
@@ -169,7 +195,9 @@
To make curl use the correct content type header use the -H option to specify
that we're sending JSON data:
- curl -k -X PUT -d <json> <url>
+```
+$ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d <json> <url>
+```
A PUT operation on an object requires a complete object. For partial updates
there is PATCH but that is not implemented yet. As a workaround individual
@@ -177,18 +205,15 @@
For example, make changes to the requested_host.json file and do a PUT (upload):
- $ cat requested_host.json
- {"data": "xyz.openbmc_project.State.Host.Transition.On"}
-
- curl -k -X PUT -T requested_host.json \
- https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
-
+```
+$ cat requested_host.json
+{"data": "xyz.openbmc_project.State.Host.Transition.Off"}
+$ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -T requested_host.json https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
+```
Alternatively specify the json inline with -d:
-
- curl -k -X PUT \
- -d '{"data": "xyz.openbmc_project.State.Host.Transition.On"}' \
- https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
-
+```
+$ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": "xyz.openbmc_project.State.Host.Transition.On"}' https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
+```
When using '-d' just remember that json requires quoting.
## HTTP POST operations
@@ -196,19 +221,16 @@
when the client doesn't know where to put it. OpenBMC does not support creating
new resources via REST so any attempt to create a new resource will result in a
HTTP 403 (Forbidden).
-
These also require a json formatted payload.
+To delete logging entries:
-To invoke a method with parameters (Downloading a Tar image via TFTP):
-
- curl -k -X POST -d '{"data": ["<Image Tarball>", "<TFTP Server>"]}' \
- https://${bmc}/xyz/openbmc_project/software/action/DownloadViaTFTP
-
+```
+$ curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/logging/action/DeleteAll
+```
To invoke a method without parameters (Factory Reset of BMC and Host):
-
- curl -k -X POST -d '{"data":[]}' \
- https://${bmc}/xyz/openbmc_project/software/action/Reset
-
+```
+$ curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/software/action/Reset
+```
## HTTP DELETE operations
DELETE operations are for removing instances. Only D-Bus objects (instances) can
be removed. If the underlying D-Bus object implements the
@@ -216,55 +238,72 @@
`xyz.openbmc_project.Object.Delete` is not implemented, the REST server will
return a HTTP 403 (Forbidden) error.
-For example, to delete the event record with ID 1:
+For example, to delete a event record:
- curl -k -X DELETE https://${bmc}/xyz/openbmc_project/logging/entry/1
+Display logging entries:
+```
+$ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X GET https://${bmc}/xyz/openbmc_project/logging/entry/enumerate
+```
+
+Then delete the event record with ID 1:
+
+```
+$ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X DELETE https://${bmc}/xyz/openbmc_project/logging/entry/1
+```
## Uploading images
It is possible to upload software upgrade images (for example to upgrade the BMC
or host software) via REST. The content-type should be set to
"application/octet-stream".
-For example, to upload an image:
+For example, to upload an image:(the `<file_to_upload>` must be a tar ball)
- curl -k -H "Content-Type: application/octet-stream" \
- -X POST -T <file_to_upload> https://${bmc}/upload/image
+```
+$ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/octet-stream" -X POST -T <file_to_upload> https://${bmc}/upload/image
+```
In above example, the filename on the BMC will be chosen by the REST server.
It is possible for the user to choose the uploaded file's remote name:
- curl -k -H "Content-Type: application/octet-stream" \
- -X PUT -T foo https://${bmc}/upload/image/bar
+```
+curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/octet-stream" -X PUT -T foo https://${bmc}/upload/image/bar
+```
In above example, the file foo will be saved with the name bar on the BMC.
-The operation will either return the version id (hash) of the uploaded file
-on success:
+The operation will either return the version id (hash) of the uploaded file on success:
- {
- "data": "ffdaab9b",
- "message": "200 OK",
- "status": "ok"
- }
+```
+{
+ "data": "afb92384",
+ "message": "200 OK",
+ "status": "ok"
+}
+```
-or an error message:
+or an error message
- {
- "data": {
- "description": "Version already exists or failed to be extracted"
- },
- "message": "400 Bad Request",
- "status": "error"
- }
+```
+{
+ "data": {
+ "description": "Version already exists or failed to be extracted"
+ },
+ "message": "400 Bad Request",
+ "status": "error"
+}
+```
+
+For more details on uploading and updating software, see:
+https://github.com/openbmc/docs/tree/master/code-update
## Event subscription protocol
-It is possible to subscribe to events, of interest, occurring on the BMC. The
-implementation on the BMC uses WebSockets for this purpose, so that clients
+It is possible to subscribe to events, of interest, occurring on the BMC.
+The implementation on the BMC uses WebSockets for this purpose, so that clients
don't have do employ polling. Instead, the rest server on the BMC can push
-data to clients over a websocket. The BMC can push out information
-pertaining to D-Bus InterfacesAdded and PropertiesChanged signals.
+data to clients over a websocket.
+The BMC can push out information pertaining to D-Bus InterfacesAdded and PropertiesChanged signals.
Following is a description of the event subscription protocol, with example
JS code snippets denoting client-side code.