Managing Power Systems servers by using DMTF Redfish APIs

The FSP-based Power Systems™ servers 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® Power Systems servers support DMTF Redfish API (DSP0266, version 1.0.3, published on 17 June 2016) 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 Flexible Service Processor (FSP) firmware level FW860.20, and later.

Communication prerequisites for Redfish on Power Systems servers

Depending on the current firmware level and network deployment, complete the following prerequisite tasks:
  • Upgrade the server firmware level to FW860.20.
  • Identify the IP address of the FSP (for example, this information can be deciphered from the connected HMC).
  • Set up the SSH tunnel to the FSP through the HMC.
  • 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).

Setting up the SSH tunnel

The following example shows the commands that are used to set up the SSH tunnel (local port forwarding) from a client (IP address 9.193.126.186) to the FSP (IP address 9.3.19.141) through the HMC (IP address 9.126.138.108):
Argus$ ssh -L 9000:9.3.19.141:443 hscpe@9.126.138.108

hscpe@9.126.138.108's password: 

Last login: Wed Feb 08 11:29:20 2017 from 9.193.126.186

For more information about scripting commands over an SSH tunnel, see Opening and closing an SSH tunnel in a shell script the smart way.

Instead of sending the Redfish requests to the IP address of the FSP, set up the SSH tunnel as described in this topic and send the request to the mapped port (9000) on the client (IP address 9.193.126.186). The domain of the URI for the Redfish requests must be 9.193.126.186:9000 for this example.

Interacting with the Redfish service

To interact with the Redfish service, complete the following steps.
  1. Create an authenticated login session (POST method on the /redfish/v1/SessionService/Sessions resource.
  2. 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)
  3. To read the properties of a resource, send a GET request with the X-Auth-Token header for the URI of the resource.
  4. 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.
  5. Extract and parse the response from the Redfish service containing 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/

IBM publishes the schema files for original equipment manufacturer (OEM) extensions to the Redfish schema (for example, the EnergyScale™ extension for better utilization of power).

The OEM schema files that are published by IBM are identified by the file name prefix of IBMEnterprise in the namespace of the schema. For example, IBMEnterpriseEnergyScale.v1_0_0.json.

OEM schema files that are published by IBM can be downloaded from the IBM Schema repository at http://public.dhe.ibm.com/systems/power/redfish/schemas/v1/.

Validating the response (JSON body) returned by the Redfish service

Response that is returned by the Redfish service contains the @odata.type property. The value of the property @odata.type in the response is a string of the format *#<namespace>.<type>, where the <namespace> is of the format <name>.<ver>.

When the namespace contains the prefix IBMEnterprise, the namespace is an OEM type that is defined by IBM and its schema file can be downloaded from the IBM schema repository.

When the namespace does not contain the prefix IBMEnterprise, the namespace is a standard type that is defined by DMTF and its schema file can be downloaded from the DMTF schema repository.

Resources supported by the Redfish service

In firmware level that is at level FW860.30, the following resources are modeled in the Redfish implementation:
  • Service
    • Service Root: https://<ip:port>/redfish/v1
    • Session Service: https://<ip:port>/redfish/v1/SessionService
    • Session Collection: https://<ip:port>/redfish/v1/SessionService/Sessions
    • Session Resource: https://<ip:port>/redfish/v1/SessionService/Sessions/<id>
    • System Collection: https://<ip:port>/redfish/v1/Systems
    • System Resource: https://<ip:port>/redfish/v1/Systems/<server-id>
    • EnergyScale : https://<ip:port>/redfish/v1/Systems/<server-id>/EnergyScale
      Note: Where:
      • ip is the IP address of the FSP or the localhost IP address of the SSH tunnel
      • port is the default HTTPS port (443) or the local port of the SSH tunnel
      • id is the session identifier
      • server-id is the server name that is returned by the Redfish service. The server name is a part of the @odata.id parameter value that is included in the response to the request for the Systems Collection. In the following example, the server name is Server-8408-E8E-1067A9V in the @odata.id parameter: "@odata.id": "/redfish/v1/Systems/Server-8408-E8E-1067A9V"
      • chassis-id is the serial number of the CEC enclosure
  • Chassis
    • Chassis Collection: https://<ip:port>/redfish/v1/Chassis
    • Chassis Resource: https://<ip:port>/redfish/v1/Chassis/<chassis-id>
    • Thermal Resource: https://<ip:port>/redfish/v1/Chassis/<chassis-id>/Thermal
      Note: Fan status is available under the Thermal Resource.
    • Power Resource: https://<ip:port>/redfish/v1/Chassis/<chassis-id>/Power
      Note: Power supply status is available under the Power Resource.
    Note: Where:
    • ip is the IP address of the FSP or the localhost IP address of the SSH tunnel
    • port is the default HTTPS port (443) or the local port of the SSH tunnel
    • chassis-id is the serial number of the CEC enclosure
  • Processor
    • Processor Collection: https://<ip:port>/redfish/v1/Systems/<server-id>/Processors
    • Processor Resource: https://<ip:port>/redfish/v1/Systems/<server-id>/Processors/<proc-id>
    • Core Resource: https://<ip:port>/redfish/v1/Systems/<server-id>/Processors/<proc-id>/Cores/<core-id>
      Note: Where:
      • ip is the IP address of the FSP or the localhost IP address of the SSH tunnel
      • port is the default HTTPS port (443) or the local port of the SSH tunnel
      • server-id is the server name that is returned by the Redfish service. The server name is a part of the @odata.id parameter value that is included in the response to the request for the Systems Collection. In the following example, the server name is Server-8408-E8E-1067A9V in the @odata.id parameter: "@odata.id": "/redfish/v1/Systems/Server-8408-E8E-1067A9V"
      • proc-id is the unique identifier of the processor
      • core-id is the unique identifier of the core in the specific processor
  • Manager Collection: https://<ip:port>/redfish/v1/Managers
  • FSP Resource: https://<ip:port>/redfish/v1/Managers/BMC
  • FSP eth0 Interface: https://<ip:port>/redfish/v1/Managers/BMC/EthernetInterfaces/ETH_0

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

The following examples show the cURL commands that can be used to access the common functions that are supported by the FSP.
  • To log in and create a secure connection with the Redfish service, run the following command:
    curl -X POST -D headers.txt https://<ip:port>/redfish/v1/SessionService/Sessions

 -d ‘{"UserName":"admin", "Password":"admin"}’

    Where ip is the IP address of the FSP and port is the default port of the ASMI. After the user logs in, value of the X-Auth-Token header must be saved for requests that might require authentication, and the value Location header must be saved because it is the unique URI for the session and these values are required to log off from the session.

  • To read the Service Root document, run the following command:
    curl -k -H "X-Auth-Token: <authtoken>" -X GET https://<ip:port>/redfish/v1/
  • To read the collection of System ID at this instance, run the following command:
    curl -k -H "X-Auth-Token: <authtoken>" -X GET https://<ip:port>/redfish/v1/Systems
  • To read the System information, run the following command:
    curl -k -H "X-Auth-Token: <authtoken>" -X GET https://<ip:port>/redfish/v1/Systems/<system-id>

    Where system-id is the machine type and model (MTM) of the system and the serial number. The format for system-id is Server-MTM-SerialNumber. To get the system-id, perform the GET operation on the System collection resource.

  • To modify the number of slots that are enabled for Enlarged Capacity I/O in the node or chassis, run the following command:
    curl -k -H "X-Auth-Token: <authtoken>" -X PATCH https://<ip:port>/redfish/v1/Chassis/

<chassis-id>; -d '{"Oem" : {"IBMEnterpriseChassis" : {"HugeDynamicDMAWindowSlotCount" : "9"}}}'
  • To modify the power saver parameters for CPU that is in idle state, run the following command:
    curl -k -H "X-Auth-Token: <authtoken>" -X PATCH https://<ip>/redfish/v1/Systems/

<system-id>/EnergyScale -d '{

   "CPUIdlePowerSaver": {

        "DelayTimeEnter": 150,

        "DelayTimeExit": 5,

        "State": "Enabled",

        "UtilizationThresholdEnter": 22,

        "UtilizationThresholdExit": 30

    }}'

    Where chassis-id is the serial number of the CEC enclosure. To get the chassis-id, perform the GET operation on the Chassis collection resource.

  • To power on the system, run the following command:
    curl -k -H "X-Auth-Token: <authtoken>" -X POST https://<ip:port>/redfish/v1/Systems/

<system-id>/Actions/Reset -d '{"ResetType":"On"}'
  • To power off the system, run the following command:
    curl -k -H "X-Auth-Token: <authtoken>" -X POST https://<ip:port>/redfish/v1/Systems/

<system -id>/Actions/Reset -d '{"ResetType":"ForceOff"}'
  • To log off or terminate the Redfish session, run the following command:
    curl -k -H "X-Auth-Token: <authtoken>" -X DELETE https://<ip:port>/redfish/v1/SessionService/

Sessions/<id>;

EnergyScale schema

EnergyScale schema is an OEM extension to Redfish schema that enables the configuration of tunable parameters for better utilization of power in IBM Power Systems servers.



Last updated: Mon, June 05, 2017