Managing the system by using DMTF Redfish APIs

Edit online

eBMC-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® eBMC-based systems support DMTF Redfish API (DSP0266, version, which is 1.12.0 published on 18 January 2021) 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.

Copyright Notice: Copyright © 2015, 2023 DMTF. All rights reserved.

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

eBMC-based systems support Redfish APIs on firmware level FW1020, or later.

Communication prerequisites for Redfish on eBMC-based servers

Depending on the current firmware level and network deployment, complete the following prerequisite tasks:
  • Upgrade the server firmware level to FW1020, or later.
  • Identify the IP address of the eBMC.
  • 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.
  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 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 eBMC-based systems. This list does not include collections.

  • AccountService
  • Action Info
  • Assemblies
  • AttributeRegistry
  • BIOS
  • Certificate
  • CertificateLocations
  • CertificateService
  • Chassis
  • ComputerSystem
  • Drive
  • EnvironmentMetrics
  • EthernetInterface
  • Event
  • EventDestination
  • EventService
  • FabricAdapter
  • Fan
  • JsonSchemaFile
  • License
  • LicenseService
  • LogEntry
  • LogService
  • Manager
  • ManagerAccount
  • ManagerNetworkProtocol
  • Memory
  • Message
  • MessageRegistry
  • MessageRegistryFile
  • MetricDefinition
  • MetricReport
  • MetricReportDefinition
  • PCIeDevice
  • PCIeSlots
  • Port
  • PowerSubsystem
  • PowerSupply
  • PowerSupplyMetrics
  • PrivilegeRegistry
  • Processor
  • Role
  • Sensor
  • ServiceRoot
  • Session
  • SessionService
  • SoftwareInventory
  • Storage
  • Task
  • TaskService
  • TelemetryService
  • ThermalSubsystem
  • UpdateService
OEM
  • OemAssembly
  • OemChassis
  • OemComputerSystem
  • OemLogEntry
  • OemLogEntryAttachment
  • OemManager
  • OemManagerAccount
  • OemCPCIeDevice
  • OemPCIeSlots
  • OemPowerSupplyMetrics
  • OemServiceRoot
  • OemSession
  • OemUpdateService

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 eBMC Redfish APIs:
Note: In all cURL commands, ${BMC} is the IP address of the eBMC, <username> is name of the eBMC account, and <password> is the password of the eBMC account.
  • To view major collections, run the following commands:
    • Chassis collection:
      curl -u <username>:<password> -k -s  https://${BMC}/redfish/v1/Chassis
    • Manager collection:
      curl -u <username>:<password> -k -s  https://${BMC}/redfish/v1/Managers
    • System collection:
      curl -u <username>:<password> -k -s  https://${BMC}/redfish/v1/Systems
  • To view the chassis, manager, and system resources, run the following commands:
    • Chassis resource:
      curl -u <username>:<password> -k -s  https://${BMC}/redfish/v1/Chassis/chassis
    • Manager resource:
      curl -u <username>:<password> -k -s  https://${BMC}/redfish/v1/Managers/bmc
    • System resource:
      curl -u <username>:<password> -k -s  https://${BMC}/redfish/v1/Systems/system
  • To perform host power control operations, run the following commands:
    • Host power on:
      curl -u <username>:<password> -k -s -X POST https://${BMC}/redfish/v1/Systems/system/Actions/ComputerSystem.Reset -d '{"ResetType": "On"}'
    • Host soft power off:
      curl -u <username>:<password> -k -s -X POST https://${BMC}/redfish/v1/Systems/system/Actions/ComputerSystem.Reset -d '{"ResetType": "GracefulShutdown"}'
    • Host hard power off:
      curl -u <username>:<password> -k -s -X POST https://${BMC}/redfish/v1/Systems/system/Actions/ComputerSystem.Reset -d '{"ResetType": "ForceOff"}'
    • Restart host: 
      curl -u <username>:<password> -k -s -X POST https://${BMC}/redfish/v1/Systems/system/Actions/ComputerSystem.Reset -d '{"ResetType": "GracefulRestart"}'
  • To view the log resource, run the following command:
    curl -u <username>:<password> -k -s https://${BMC}/redfish/v1/Systems/system/LogServices/EventLog/Entries
  • To view the audit log resource, run the following command:
    curl -u <username>:<password> -k -s https://${BMC}/redfish/v1/Systems/system/LogServices/AuditLog/Entries
  • To view sensor resources, run the following commands:
    • PowerSubsystem resource:
      curl -u <username>:<password> -k -s https://${BMC}/redfish/v1/Chassis/chassis/PowerSubsystem
    • ThermalSubsystem resource:
      curl -u <username>:<password> -k -s https://${BMC}/redfish/v1/Chassis/chassis/ThermalSubsystem
    • Sensor resource:
      curl -u <username>:<password> -k -s https://${BMC}/redfish/v1/Chassis/chassis/Sensors
  • To view inventory resources, run the following commands:
    • Memory resource:
      curl -u <username>:<password> -k -s https://${BMC}/redfish/v1/Systems/system/Memory
    • Processor resource:
      curl -u <username>:<password> -k -s https://${BMC}/redfish/v1/Systems/system/Processors
    • Power supply 0 resource:
      curl -u <username>:<password> -k -s https://${BMC}/redfish/v1/Chassis/powersupply0
    • Power supply 1 resource:
      curl -u <username>:<password> -k -s https://${BMC}/redfish/v1/Chassis/powersupply1
  • To update the firmware, run the following commands:
    • By using an image file from your system: 
      curl -u <username>:<password> -curl k -s  -H "Content-Type: application/octet-stream" -X POST -T <image file path> https://${BMC}/redfish/v1/UpdateService
  • To create a new local account, run the following command:
    • curl -u <username>:<password> -k -s -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 -u <username>:<password> -k -s -X POST https://${BMC}/redfish/v1/AccountService/Accounts/admin -d '{"Password": "NEWPASSWORD"}'
      Where admin is the account name or user ID and NEWPASSWORD is the new password.

For more information about selecting a username, password, or role, see User management.

Interacting with the Redfish service

To interact with the Redfish service, complete the steps from the following authentication options:

Token-based authentication
  1. Create an authenticated login session (POST method on the /redfish/v1/SessionService/Sessions resource).
    • For example, 
      curl -k -H "Content-Type: application/json" -X POST -D headers.txt https://${bmc}/redfish/v1/SessionService/Sessions -d '{"UserName":"admin","Password":"admin"}'
  2. Extract and save the following details:
    • Authentication token (found in the X-Auth-Token header of the response). For example, in the header.txt file above export bmc_token=<token>.
    • 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.
    • For example, 
      curl -k -H "X-Auth-Token: $token" https://${bmc}/redfish/v1/Chassis
  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.
    • For example, 
      curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PATCH https://${bmc}/redfish/v1/Managers/bmc/NetworkProtocol -d '{"NTP":{"ProtocolEnabled": true}}'
  5. Extract and parse the response from the Redfish service that contains the JSON body.

Basic authentication

  1. To pass the username and password as part of the request, run the following command:
    • curl -u <username>:<password> -k -s  https://${BMC}/redfish/v1/SessionService