Cisco UCS C-Series Servers REST API Programmer's Guide, Release 6.0

Overview

This chapter provides detailed information about the Redfish (DMTF specification) APIs that are supported in Server Diagnostics Utility (SDU) framework which has a unified, modular, and extensible framework to diagnose the UCS Servers hardware components.

Workflow

The SDU Redfish API workflow includes the following steps:

Boot the Diagnostics OS
Start the Diagnostics
Restore the Server

Boot the Diagnostics OS

Request

POST /redfish/v1/Managers/CIMC/Actions/Oem/CiscoUCSExtensions.HostOSBootManagement

{
	“ImageRepository”: “10.0.0.20/home/nfsshare/ucs-diag-7.1.1.240016.iso”,
	“TransferProtocol”: “VMEDIA-NFS”,
	“BootOption”: “Immediate”,
	“Mode”: “Diagnostics”
}

Check the Task ID request to find out the progress.

curl -k -u admin:Abc@123 https://10.0.0.10/redfish/v1/TaskService/Tasks/37

Sample Request

curl -k -u admin:Abc@123 -X POST 
https://10.0.0.30/redfish/v1/Managers/CIMC/Actions/Oem/CiscoUCSExtensions.HostOSBootManagement
-d '{"ImageRepository": "10.0.0.10/nfsshare/sdu/7.1.1/ucs-diag-7.1.1.240023.iso",
"TransferProtocol": "VMEDIA-NFS","BootOption": "Immediate","Mode":"Diagnostics"}'

Sample Response


{
"@odata.id": "/redfish/v1/TaskService/Tasks/37",
"@odata.type": "#Task.v1_5_0.Task",
"@odata.context": "/redfish/v1/$metadata#Task.Task",
"Id": "37",
"Name": "HSU-Diagnostics",
"StartTime": "2024-10-15T05:30:18+00:00",
"EndTime": "2024-10-15T05:37:55+00:00",
"PercentComplete": 100,
"TaskState": "Completed",
"Messages": [{
"@odata.type": "#Message.v1_1_1.Message",
"MessageId": "Base.1.13.0.Success",
"Message": "Successfully Completed Request",
"MessageArgs": [],
"Severity": "OK"
}],
"TaskMonitor": "/redfish/v1/TaskService/Oem/TaskMonitor/37"

Table 1. Action Parameters

Property

Type

Notes

ImageRepository (required)

String

Path of the SDU ISO downloaded from the CCO.

BootOption (optional)

String (Enum)

Option to boot the diagnostics OS.

The default value is OnNextBoot.

OnNextBoot
Immediate

Mode (required)

String

Diagnostics

TransferProtocol (optional)

String

Network protocol used by the HostOSBootManagement action to retrieve the ISO image from image repository.

The default value is VMEDIA-HTTPS.

VMEDIA-HTTPS
VMEDIA-CIFS
VMEDIA-NFS
HTTPS
CIFS
NFS
LOCAL-HOST

Note

HTTPS, CIFS and NFS are supported only for Cisco UCS C-series M5 servers

Username (optional)

String

Username to be used when accessing files from ImageRepository.

Password (optional)

String

Password to be used when accessing files from ImageRepository.

Get Diagnostics Supported Components

Request

curl -k -u admin:Abc@123 https://10.0.0.1/redfish/v1/Chassis/1/Oem/Cisco/CiscoServerDiagnostics

Response

{
        "@odata.id":    "/redfish/v1/Chassis/1/Oem/Cisco/CiscoServerDiagnostics",
        "@odata.type":  "#CiscoServerDiagnostics.v1_0_0.CiscoServerDiagnostics",
        "@odata.context":       "/redfish/v1/$metadata#CiscoServerDiagnostics.CiscoServerDiagnostics",
        "Name": "Server Diagnostics",
        "Description":  "This object is intended to identify the failures in the hardware.",
        "Components":   [{
                        "Id":   "/redfish/v1/Systems/WZP252306YT/EthernetInterfaces",
                        "SupportedTestTypes":   ["Quick", "Comprehensive"]
                }, {
                        "Id":   "/redfish/v1/Systems/WZP252306YT/Processors",
                        "SupportedTestTypes":   ["Quick", "Comprehensive"]
                }, {
                        "Id":   "/redfish/v1/Systems/WZP252306YT/Storage",
                        "SupportedTestTypes":   ["Quick", "Comprehensive"]
                }, {
                        "Id":   "/redfish/v1/Systems/WZP252306YT/Memory",
                        "SupportedTestTypes":   ["Quick", "Comprehensive"]
                }, {
                        "Id":   "/redfish/v1/Managers/CIMC",
                        "SupportedTestTypes":   ["Quick", "Comprehensive"]
                }, {
                        "Id":   "/redfish/v1/Systems/WZP252306YT/PCIeDevices/3",
                        "SupportedTestTypes":   ["Quick", "Comprehensive"]
                }, {
                        "Id":   "/redfish/v1/Systems/WZP252306YT/EthernetInterfaces/MLOM.0",
                        "SupportedTestTypes":   ["Quick", "Comprehensive"]
                }, {
                        "Id":   "/redfish/v1/Systems/WZP252306YT/EthernetInterfaces/MLOM.1",
                        "SupportedTestTypes":   ["Quick", "Comprehensive"]
                }, {
                        "Id":   "/redfish/v1/Systems/WZP252306YT/PCIeDevices/FRONT-NVME-1",
                        "SupportedTestTypes":   ["Quick", "Comprehensive"]
                }, {
                        "Id":   "/redfish/v1/Systems/WZP252306YT/PCIeDevices/FRONT-NVME-2",
                        "SupportedTestTypes":   ["Quick", "Comprehensive"]
                }, {
                        "Id":   "/redfish/v1/Systems/WZP252306YT/PCIeDevices/FRONT-NVME-3",
                        "SupportedTestTypes":   ["Quick", "Comprehensive"]
                }, {
                        "Id":   "/redfish/v1/Systems/WZP252306YT/PCIeDevices/FRONT-NVME-4",
                        "SupportedTestTypes":   ["Quick", "Comprehensive"]
                }, {
                        "Id":   "/redfish/v1/Systems/WZP252306YT/Processors/CPU1",
                        "SupportedTestTypes":   ["Quick", "Comprehensive"]
                }, {
                        "Id":   "/redfish/v1/Systems/WZP252306YT/Storage/MRAID",
                        "SupportedTestTypes":   ["Quick", "Comprehensive"]
                }, {
                        "Id":   "/redfish/v1/Systems/WZP252306YT/Storage/MSTOR-RAID",
                        "SupportedTestTypes":   ["Quick", "Comprehensive"]
                }, {
                        "Id":   "/redfish/v1/Systems/WZP252306YT",
                        "SupportedTestTypes":   ["Quick", "Comprehensive"]
                }, {
                        "Id":   "/redfish/v1/Systems/WZP252306YT/Storage/MSTOR-RAID/Drives/253",
                        "SupportedTestTypes":   ["Quick", "Comprehensive"]
                }, {
                        "Id":   "/redfish/v1/Systems/WZP252306YT/Storage/MSTOR-RAID/Drives/254",
                        "SupportedTestTypes":   ["Quick", "Comprehensive"]
                }, {
                        "Id":   "/redfish/v1/Systems/WZP252306YT/Storage/MSTOR-RAID/Drives",
                        "SupportedTestTypes":   ["Quick", "Comprehensive"]
                }],
        "Components@odata.count":       19,
        "Actions":      {
                "#CiscoServerDiagnostics.Start":        {
                        "target":       "/redfish/v1/Chassis/1/Oem/Cisco/CiscoServerDiagnostics/Actions/CiscoServerDiagnostics.Start",
                        "@odata.type":  "#CiscoServerDiagnostics.v1_0_0.CiscoServerDiagnostics",
                        "Targets@Redfish.AllowableValues":      ["Array of Redfish OData IDs indicating which components are to be diagnosed. Empty list to indicate all the components."],
                        "ExcludeTargets@Redfish.AllowableValues":       ["Array of Redfish OData IDs indicating which components to be excluded from diagnostics."],
                        "TestType@Redfish.AllowableValues":     ["The type of diagnostic test to be started. Allowable values are Quick and Comprehensive. By default, comprehensive tests will be started."]
                },
                "#CiscoServerDiagnostics.Cancel":       {
                        "target":       "/redfish/v1/Chassis/1/Oem/Cisco/CiscoServerDiagnostics/Actions/CiscoServerDiagnostics.Cancel",
                        "@odata.type":  "#CiscoServerDiagnostics.v1_0_0.CiscoServerDiagnostics",
                        "Targets@Redfish.AllowableValues":      ["Array of Redfish OData IDs indicating which components are to be cancelled. Empty list to indicate all the components."]
                }
        }

Table 2. Action Parameters

Properties

Type

Notes

@odata.id

String (URI)

The unique identifier for a resource.

@odata.type

String

The type of a resource.

@odata.context

String

The OData description of a payload.

Description

String

The description of this resource.

Name

String

The name of the resource.

Components

Array

An array of supported components links and its configurations.

Id

String (URI)

The unique identifier for the supported component.

SupportedTestTypes

Array

An array of supported test types.

Possible property values:

Quick
Comprehensive

Note

Quick takes 30-60 minutes to complete.

Comprehensive takes many hours to complete.

Actions {}

The Redfish actions available for this Resource.

Start the Diagnostics

Request

curl -k -u admin:Abc@123 -X POST -H "Content-Type:application/json" 
-d '{"Targets": ["/redfish/v1/Systems/WZP25120AZG/Storage"],
"TestType": "Quick","ExcludeTargets":["/redfish/v1/Systems/WZP25120AZG/Storage/MRAID1"]}' 
https://10.0.0.12/redfish/v1/Chassis/1/Oem/Cisco/CiscoServerDiagnostics/Actions/CiscoServerDiagnostics.Start
{
"Messages": [],
"Id": "763",
"Name": "HSU-start-diagnostics",
"StartTime": "2024-10-13T12:02:38+00:00",
"TaskState": "New",
"PercentComplete": 0,
"@odata.id": "/redfish/v1/TaskService/Tasks/763",
"@odata.type": "#Task.v1_4_0.Task"

Response

curl -k -u admin:Abc@123 https://10.0.0.12/redfish/v1/TaskService/Tasks/763
{
"@odata.id": "/redfish/v1/TaskService/Tasks/763",
"@odata.type": "#Task.v1_5_0.Task",
"@odata.context": "/redfish/v1/$metadata#Task.Task",
"Id": "763",
"Name": "HSU-start-diagnostics",
"StartTime": "2024-10-13T12:02:38+00:00",
"EndTime": "2024-10-13T12:09:11+00:00",
"PercentComplete": 100,
"TaskState": "Completed",
"TaskStatus": "OK",
"Messages": [{
"@odata.type": "#Message.v1_0_6.Message",
"MessageId": "Base.1.4.New",
"Message": "The selected test types for this task: Quick",
"MessageArgs": ["Quick"],
"Severity": "OK",
"Resolution": "None"
}, {
"@odata.type": "#Message.v1_0_6.Message",
"MessageId": "CiscoUcsSdu.1.0.0.TestPassed",
"Message": "The component '/redfish/v1/Systems/WZP25120AZG/Storage/MSTOR-RAID/Drives/254' has passed the diagnostics test.",
"MessageArgs": ["/redfish/v1/Systems/WZP25120AZG/Storage/MSTOR-RAID/Drives/254"],
"Severity": "OK",
"Resolution": "None"
}, {
"@odata.type": "#Message.v1_0_6.Message",
"MessageId": "CiscoUcsSdu.1.0.0.TestPassed",
"Message": "The component '/redfish/v1/Systems/WZP25120AZG/Storage/MSTOR-RAID' has passed the diagnostics test.",
"MessageArgs": ["/redfish/v1/Systems/WZP25120AZG/Storage/MSTOR-RAID"],
"Severity": "OK",
"Resolution": "None"
}, {
"@odata.type": "#Message.v1_0_6.Message",
"MessageId": "CiscoUcsSdu.1.0.0.TestPassed",
"Message": "The component '/redfish/v1/Systems/WZP25120AZG/Storage/MSTOR-RAID/Drives/253' has passed the diagnostics test.",
"MessageArgs": ["/redfish/v1/Systems/WZP25120AZG/Storage/MSTOR-RAID/Drives/253"],
"Severity": "OK",
"Resolution": "None"
}, {
"@odata.type": "#Message.v1_1_1.Message",
"MessageId": "Base.1.13.0.Success",
"Message": "Successfully Completed Request",
"MessageArgs": [],
"Severity": "OK"
}],
"TaskMonitor": "/redfish/v1/TaskService/Oem/TaskMonitor/763"
}

Note

The below mentioned request can be used to trigger diagnostics on all supported domponents present in the server.

curl -k -u admin:Abc@123 -X POST -H "Content-Type:application/json" 
-d '{"Targets": [],"TestType": "Quick"}' 
https://10.0.0.12/redfish/v1/Chassis/1/Oem/Cisco/CiscoServerDiagnostics/Actions/CiscoServerDiagnostics.Start

Table 3. Action Parameters
Properties	Type	Notes
Targets (optional)	Array	An array of the component targets which must be diagnosed. The default is to diagnose all the supported components.
ExcludeTargets (optional)	Array	An array of the component targets which must be excluded from diagnosing.
TestType (optional)	String (Enum)	Possible propery values: Quick Comprehensive The default value is Comprehensive. Note: Quick takes 30-60 minutes to complete. Comprehensive takes many hours to complete.

Restoring the Server

Request

POST /redfish/v1/Systems/WZP244208SH/Actions/ComputerSystem.Reset

{
“ResetType”: “GracefulRestart”
}

curl -X POST -d '{"ResetType": "GracefulRestart"}' 
10.0.0.1:444/redfish/v1/Systems/WZP24140D66/Actions/ComputerSystem.Reset

Response

{
        "Messages":     [],
        "Id":   "80",
        "Name": "Computer System Reset - Graceful Restart",
        "StartTime":    "2023-07-31T11:24:50+05:30",
        "TaskState":    "Running",
        "@odata.id":    "/redfish/v1/TaskService/Tasks/80",
        "@odata.type":  "#Task.v1_4_0.Task"
}

Request

curl 127.0.0.1:444/redfish/v1/TaskService/Tasks/80

Response

{
        "@odata.id":    "/redfish/v1/TaskService/Tasks/80",
        "@odata.type":  "#Task.v1_5_0.Task",
        "@odata.context":       "/redfish/v1/$metadata#Task.Task",
        "Id":   "80",
        "Name": "Computer System Reset - Graceful Restart",
        "StartTime":    "2023-07-31T11:24:50+05:30",
        "EndTime":      "2023-07-31T11:25:11+05:30",
        "PercentComplete":      100,
        "TaskState":    "Completed",
        "TaskStatus":   "OK",
        "Messages":     [{
                        "@odata.type":  "#Message.v1_1_1.Message",
                        "MessageId":    "Base.1.13.0.Success",
                        "Message":      "Successfully Completed Request",
                        "MessageArgs":  [],
                        "Severity":     "OK"
                }],
        "TaskMonitor":  "/redfish/v1/TaskService/Oem/TaskMonitor/80"
}

Cancel Diagnostics

Request

curl -k -u admin:Abc@123 -X POST 
https://10.0.0.1/redfish/v1/Chassis/ChassisID/Oem/Cisco/CiscoServerDiagnostics/Actions/CiscoServerDiagnostics.Cancel

Table 4. Action Parameters
Properties	Type	Notes
Targets (optional)	Array	An array of the component targets which must be cancelled. The default is to cancel all the queued and running targets, and end the task.

Sample Request

{
	"Targets": [
		“/redfish/v1/Systems/WZP244208SH/Processors/CPU1”,
		“/redfish/v1/Managers/CIMC”
	]
}

Bias-Free Language

Book Title

Cisco UCS C-Series Servers REST API Programmer's Guide, Release 6.0

Chapter Title

Cisco IMC REST API Commands - SDU

Results

Chapter: Cisco IMC REST API Commands - SDU

Cisco IMC REST API Commands - SDU

Overview

Boot the Diagnostics OS

Get Diagnostics Supported Components

Start the Diagnostics

Restoring the Server

Cancel Diagnostics

Was this Document Helpful?

Contact Cisco