Managing the system by using DMTF Redfish APIs

OpenBMC-based systems can be managed by using the DMTF Redfish APIs.

Overview

Redfish is a REST API used for platform management and is standardized by the Distributed Management Task Force, Inc. (http://www.dmtf.org/standards/redfish).

Redfish enables platform management tasks to be controlled by client scripts that are developed by using secure and modern programming paradigms.

The Redfish API enables provisioning of tunable parameters for better utilization of power.

IBM® OpenBMC-based systems support DMTF Redfish API (DSP0266, version 1.7.0, published on 20 May 2019) for systems management.

A copy of the Redfish schema files that are in JSON format are published by DMTF (http://redfish.dmtf.org/schemas/v1/) and are packaged in the firmware image.

The schema files that are distributed in the chip enable proper functioning of the APIs in deployments that have no wide area network (WAN) connectivity.

Note: The Redfish API is enabled by default and the Redfish service cannot be enabled or disabled by the user.

Firmware levels

Redfish APIs are supported on OpenPOWER (OP) firmware level OP940, or later.

Communication prerequisites for Redfish on OpenBMC-based servers

Depending on the current firmware level and network deployment, complete the following prerequisite tasks:

Upgrade the server firmware level to OP940, or later.
Identify the IP address of the BMC.
Install and run cURL (https://curl.haxx.se/) with the method, Uniform Resource Indicator (URI), and the request body as parameters to communicate with the Redfish service.
Install Python on the client system (typically a Linux® host).
Optionally, install and run DMTF Redfishtool (https://github.com/DMTF/Redfishtool).

Interacting with the Redfish service

To interact with the Redfish service, complete the following steps.

Create an authenticated login session (POST method on the /redfish/v1/SessionService/Sessions resource).
Extract and save the following details:
- Authentication token (found in the X-Auth-Token header of the response)
- Session URI (found in the Location header of the response)
To read the properties of a resource, send a GET request with the X-Auth-Token header for the URI of the resource.
To set a property of a resource, send a PATCH request with the X-Auth-Token header for the URI of the resource, the property name, type, and value encoded as a JSON body.
Extract and parse the response from the Redfish service that contains the JSON body.

Redfish service home page URI

The Redfish service home page URI (also known as the service ROOT) can be accessed by retrieving the URI: https://<ip:port>/redfish/v1. The response to this URI is a high-level site map that enables a traversal of the Redfish service by using a hypermedia API paradigm.

Interpreting the data returned by the Redfish service

The format and structure of the data is defined in the schema files. Schema files are JSON files that describe the data that is sent by the Redfish service. You can use the schema files to understand the data that is sent by the Redfish service and to validate the response that is sent by the Redfish service.

Location of the schema files

DMTF publishes the schema files for the standard data that is used in Redfish.

The Redfish schema files in JSON format are hosted in the DMTF schema repository at http://redfish.dmtf.org/schemas/v1/

Supported schema files

The following schema files are supported for OpenBMC-based systems:

Account
AccountCollection
AccountService
Certificate
CertificateCollection
CertificateLocations
CertificateService
Chassis
ChassisCollection
ComputerSystem
ComputerSystemCollection
EthernetInterface
EthernetInterfaceCollection
LogEntry
LogService
LogServiceCollection
Manager
ManagerCollection
ManagerNetworkProtocol
Memory
MemoryCollection
Processor
ProcessorCollection
Role
RoleCollection
ServiceRoot
Session
SessionCollection
SessionService
SoftwareInventory
SoftwareInventoryCollection
ThermalPower
UpdateService

Accessing the common system management functions on the Redfish service by using cURL command

The following examples show the client URL (cURL) commands that can be used to access the common functions that are supported by the OpenBMC Redfish APIs:

Note: In all cURL commands, ${BMC} is the IP address of the BMC.

To view major collections, run the following commands:

Chassis collection:

curl -u root:0penBmc -k -s  https://${BMC}/redfish/v1/Chassis

Manager collection:

curl -u root:0penBmc -k -s  https://${BMC}/redfish/v1/Managers

System collection:

curl -u root:0penBmc -k -s  https://${BMC}/redfish/v1/Systems

To view the chassis, manager, and system resources, run the following commands:

Chassis resource:

curl -u root:0penBmc -k -s  https://${BMC}/redfish/v1/Chassis/chassis

Manager resource:

curl -u root:0penBmc -k -s  https://${BMC}/redfish/v1/Managers/bmc

System resource:

curl -u root:0penBmc -k -s  https://${BMC}/redfish/v1/Systems/system

To perform host power control operations, run the following commands:

Host power on:

-X POST https://${BMC}/redfish/v1/Systems/system/Actions/ComputerSystem.Reset -d '{"ResetType": "On"}'

Host soft power off:

-X POST https://${BMC}/redfish/v1/Systems/system/Actions/ComputerSystem.Reset -d '{"ResetType": "GracefulShutdown"}'

Host hard power off:

-X POST https://${BMC}/redfish/v1/Systems/system/Actions/ComputerSystem.Reset -d '{"ResetType": "ForceOff"}'

Restart host:

-X POST https://${BMC}/redfish/v1/Systems/system/Actions/ComputerSystem.Reset -d '{"ResetType": "GracefulRestart"}'

To view the host power control resource, run the following command:

curl -u root:0penBmc -k -s https://${BMC}/redfish/v1/Systems/system/Actions/

To view the log resource, run the following command:

curl -u root:0penBmc -k -s https://${BMC}/redfish/v1/Systems/system/LogServices/EventLog/Entries

To view sensor resources, run the following commands:

Power® resource:

curl -u root:0penBmc -k -s https://${BMC}/redfish/v1/Chassis/chassis/Power

Thermal resource:

curl -u root:0penBmc -k -s https://${BMC}/redfish/v1/Chassis/chassis/Thermal

Sensor resource:

curl -u root:0penBmc -k -s https://${BMC}/redfish/v1/Chassis/chassis/Sensors

To view inventory resources, run the following commands:

Memory resource:

curl -u root:0penBmc -k -s https://${BMC}/redfish/v1/Systems/system/Memory

Processor resource:

curl -u root:0penBmc -k -s https://${BMC}/redfish/v1/Systems/system/Processors

Power supply 0 resource:

curl -u root:0penBmc -k -s https://${BMC}/redfish/v1/Chassis/powersupply0

Power supply 1 resource:

curl -u root:0penBmc -k -s https://${BMC}/redfish/v1/Chassis/powersupply1

Motherboard resource:

curl -u root:0penBmc -k -s https://${BMC}/redfish/v1/Chassis/motherboard

To update the firmware, run the following commands:

By using an image file from your system:

curl -u root:0penBmc -curl k -s  -H "Content-Type: application/octet-stream" -X POST -T <image file path> https://${BMC}/redfish/v1/UpdateService

By using a Trivial File Transfer Protocol (TFTP) server:

curl -u root:0penBmc -k -s -d '{"ImageURI":"<TFTP IP Address>/<File name on TFTP server>","TransferProtocol":"TFTP"}' -X POST https://${BMC}/redfish/v1/UpdateService/Actions/UpdateService.SimpleUpdate

To create a new local account, run the following command:
- ```
curl -X POST https://${BMC}/redfish/v1/AccountService/Accounts/ -d '{"UserName": "admin", "Password": "NEWPASSWORD", "RoleId": "Administrator"}'
```
  Where admin is the name of the user that you want to create, NEWPASSWORD is the new password, and RoleId maps to the privilege role.
To change the account password, run the following command:
- ```
curl -X POST https://${BMC}/redfish/v1/AccountService/Accounts/root -d '{"Password": "NEWPASSWORD"}'
```
  Where root is the account name or user ID and NEWPASSWORD is the new password.

For more information about selecting a username, password, or role, see Local users.