Skip to main content

POST – Multipart HTTP Push update for firmware

This operation can perform an update of installed software component(s) by pushing a software image file to the URI referenced by UpdateService.MultipartHttpPushUri property. In XCC redfish service, the UpdateService.MultipartHttpPushUri property value is “/mfwupdate”.

Request URL

POST https://<BMC_IPADDR>/mfwupdate

Request body

The HTTP POST operation shall provide authentication with the sufficient privilege to access the UpdateService resource.

Response

FieldTypeError Message ID

Id

String

The created task ID.

Name

String

Task name.

Description

String

This resource represents a task for a Redfish implementation.

TaskMonitor

String

The URI of the Task Monitor for this task.

StartTime

String

The date-time stamp that the task was last started.

TaskState

String

The state of the task.

Messages

Array

This is an array of messages associated with the task.

PercentComplete

Integer

Task completion in percent.

HidePayload

Boolean

Indicates Payload object is hidden and not returned on GET.

Note
The client may optionally include HTTP multipart form data in the POST body to specify the image file name as RFC2388 specified. XCC checks this header and verity the size is supported for firmware updates, and returns code 413 when file size is too large. If the client uploads multiple files in a POST request, it returns code 400 with an error message indicating the format is not supported.

Multipart HTTP push update may be rejected with code 503 when Http Push update is in progress, and vice versa.

Status code

HTTP Status CodeError Message ID
202Accepted
400BadRequest, ActionParamMissing , ActionParamTypeError , ActionParamFormatError
413RequestEntityTooLarge
500InternalError
503ServiceUnavailable

Example

The following example with curl commands is the multipart HTTP push update procedure for UEFI/ BMC (Backup).

  • Step 1. Update HttpPushUriTargetsBusy to true.

Client should first check HttpPushUriTargetsBusy property. When the value is false, change HttpPushUriTargetsBusy property to True, in order to claim the service is occupied for firmware update. Other clients should not update firmware on this server to avoid interference.

The PATCH body is:

{
"HttpPushUriTargetsBusy" : true
}

  • Step 2. If client intends to update BMC (Backup), there is an extra step here to provide HttpPushUriTargets.

Skip this step if it is not to update BMC (Backup) firmware.

The PATCH body is:

   "HttpPushUriTargets" : [
"/redfish/v1/UpdateService/FirmwareInventory/BMC-Backup"
]

  • Step 3. Push the firmware image to the URL in MultipartHttpPushUri property.

Sample curl command is below for multipart HTTP push update request for BMC (Backup).

curl -s -k -u USERID:PASSW0RD -F 'UpdateParameters={ "Targets":[ "/redfish/v1/UpdateService/FirmwareInventory/BMC-Backup" ],"@Redfish.OperationApplyTime":"OnStartUpdateRequest"};type=application/json' -F 'UpdateFile=@/tmp/xcc/xcc-fw.upd;type=application/octet-stream' https://192.168.1.216:443/mfwupdate

The following sample JSON response is returned.

{
"Members": [
{
"@odata.id": "/redfish/v1/TaskService/Tasks/1491a59d-2abb-4e6e-9e11-84fea2c89ceb"
}
],
"@odata.type": "#TaskCollection.TaskCollection",
"@odata.id": "/redfish/v1/TaskService/Tasks",
"Members@odata.count": 1,
"@odata.etag": "\"1585198032333\"",
"Name": "Task Collection",
"Description": "This resource represents a Resource Collection of Task instances for a Redfish implementation."
}

In the response body, a new created task resource is included. And a task monitor resource is referenced in TaskMonitor property.

  • Step 4. Client needs to periodically check the URI of task for updating progress.

In the following are sample JSON responses for continuously checking a task resource. (The task Id is 1491a59d-2abb-4e6e-9e11-84fea2c89ceb)

The 1st check, task overall progress 31%. It is verifying the uploaded image.

{
"StartTime": "2020-03-26T04:47:12+00:00",
"TaskState": "Running",
"HidePayload": true,
"Name": "Task 1491a59d-2abb-4e6e-9e11-84fea2c89ceb",
"PercentComplete": 31,
"@odata.id": "/redfish/v1/TaskService/Tasks/1491a59d-2abb-4e6e-9e11-84fea2c89ceb",
"@odata.type": "#Task.v1_4_2.Task",
"Id": "1491a59d-2abb-4e6e-9e11-84fea2c89ceb",
"TaskMonitor": "/redfish/v1/TaskService/7add4883-18c6-431c-9f1b-f2f8cc43804c",
"@odata.etag": "\"1585198032627\"",
"Messages": [
{
"@odata.type": "#Message.v1_0_8.Message",
"MessageArgs": [
"1491a59d-2abb-4e6e-9e11-84fea2c89ceb",
"31"
],
"Message": "The task with id 1491a59d-2abb-4e6e-9e11-84fea2c89ceb has changed to progress 30 percent complete.",
"Severity": "OK",
"Resolution": "None.",
"MessageId": "TaskEvent.1.0.TaskProgressChanged"
},
{
"@odata.type": "#Message.v1_0_8.Message",
"Message": "Verify 1 percent complete.",
"Resolution": "None",
"Severity": "OK",
"MessageId": "LenovoFirmwareUpdateRegistry.1.0.UpdateVerifyInProgress",
"MessageArgs": [
"0"
]
}
],
"Description": "This resource represents a task for a Redfish implementation."
}

The next check, task overall progress 100%. Image applying completed. And task state is completed.

{
"StartTime": "2020-03-26T04:47:12+00:00",
"TaskState": "Completed",
"Name": "Task 1491a59d-2abb-4e6e-9e11-84fea2c89ceb",
"EndTime": "2020-03-26T04:48:36+00:00",
"HidePayload": true,
"@odata.id": "/redfish/v1/TaskService/Tasks/1491a59d-2abb-4e6e-9e11-84fea2c89ceb",
"PercentComplete": 100,
"TaskStatus": "OK",
"@odata.type": "#Task.v1_4_2.Task",
"Id": "1491a59d-2abb-4e6e-9e11-84fea2c89ceb",
"TaskMonitor": "/redfish/v1/TaskService/7add4883-18c6-431c-9f1b-f2f8cc43804c",
"Messages": [
{
"MessageArgs": [
"1491a59d-2abb-4e6e-9e11-84fea2c89ceb"
],
"Message": "The task with id 1491a59d-2abb-4e6e-9e11-84fea2c89ceb has completed.",
"Resolution": "None.",
"Severity": "OK",
"MessageId": "TaskEvent.1.0.TaskCompletedOK",
"@odata.type": "#Message.v1_0_8.Message"
},
{
"@odata.type": "#Message.v1_0_8.Message",
"MessageArgs": [],
"Message": "Successfully Completed Request",
"Severity": "OK",
"Resolution": "None",
"MessageId": "Base.1.6.Success"
},
{
"@odata.type": "#Message.v1_0_8.Message",
"Message": "Assignment 1: Resource /redfish/v1/UpdateService/FirmwareInventory/BMC-Backup SoftwareID BMC-TEI3-10 Version 95D-3.40 to Version 95D-3.40.",
"Resolution": "None",
"Severity": "OK",
"MessageId": "LenovoFirmwareUpdateRegistry.1.0.UpdateAssignment",
"MessageArgs": [
"1",
"/redfish/v1/UpdateService/FirmwareInventory/BMC-Backup",
"BMC-TEI3-10",
"95D-3.40",
"95D-3.40"
]
},
{
"@odata.type": "#Message.v1_0_8.Message",
"Message": "Assignment 1: Apply complete",
"Resolution": "None",
"Severity": "OK",
"MessageId": "LenovoFirmwareUpdateRegistry.1.0.PayloadApplyCompleted",
"MessageArgs": [
"1"
]
}
],
"@odata.etag": "\"1585198116883\"",
"Description": "This resource represents a task for a Redfish implementation."
}

  • Step 5. Client needs to check the task until its state changed to complete or exception. And handle exceptions according to task messages returned.

A sample task response with exception is below.

{
"StartTime": "2020-03-26T06:02:32+00:00",
"TaskState": "Exception",
"Name": "Task 55b1abaf-a678-4869-aef5-1a57ef76ad3b",
"EndTime": "2020-03-26T06:02:33+00:00",
"HidePayload": true,
"@odata.id": "/redfish/v1/TaskService/Tasks/55b1abaf-a678-4869-aef5-1a57ef76ad3b",
"PercentComplete": 30,
"TaskStatus": "Warning",
"TaskMonitor": "/redfish/v1/TaskService/edece36d-5bcd-4ee1-9a5e-3e498412d502",
"Id": "55b1abaf-a678-4869-aef5-1a57ef76ad3b",
"@odata.type": "#Task.v1_4_2.Task",
"@odata.etag": "\"1585202553905\"",
"Messages": [
{
"@odata.type": "#Message.v1_0_8.Message",
"Message": "The task with id 55b1abaf-a678-4869-aef5-1a57ef76ad3b has completed with warnings.",
"MessageArgs": [
"55b1abaf-a678-4869-aef5-1a57ef76ad3b"
],
"Severity": "Warning",
"Resolution": "None.",
"MessageId": "TaskEvent.1.0.TaskCompletedWarning"
},
{
"MessageArgs": [
"57",
"Invalid URI"
],
"Message": "Verify failed, return code=57 - return message: Invalid URI",
"Resolution": "Resubmit the request. If the problem persists, consider resetting the service.",
"Severity": "Warning",
"MessageId": "LenovoFirmwareUpdateRegistry.1.0.UpdateVerifyFailed",
"@odata.type": "#Message.v1_0_8.Message"
}
],
"Description": "This resource represents a task for a Redfish implementation."
}

  • Step 6. If the target is BMC (Backup), there is an extra step here to clear HttpPushUriTargets.

Skip this step if it is not BMC (Backup) firmware updated.

The PATCH body is:

{
"HttpPushUriTargets" : [ ]
}

  • Step 7. Update HttpPushUriTargetsBusy to false.

When the firmware update procedure is completed, change HttpPushUriTargetsBusy property to false, in order to release the service to other clients for firmware update.

The PATCH body is:

{
"HttpPushUriTargetsBusy" : false
}