Skip to main content

POST – 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.HttpPushUri property. In XCC redfish service, the UpdateService.HttpPushUri property value is “/fwupdate”.

Request URL​

POST https://<BMC_IPADDR>/fwupdate

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 "Content-Length" header in the POST request to indicate the POST body size. XCC checks this header and verity the size is supported for firmware updates. If the file size is beyond what the service can support, it returns code 413 with error messages indicating file size too large.

Http Push update may be rejected with code 503 when Multipart 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 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 HttpPushUri property.

Sample curl command is below for HTTP push update request for UEFI.

curl -s -k -u USERID:PASSW0RD --data-binary @/tmp/uefi/lnvgy_fw_uefi_ive148m-2.41_anyos_32-64.uxz https://192.168.1.126:443/fwupdate
Note
You can add ‘-v’ to the curl command to observe file transfer progress.

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

curl -s -k -u USERID:PASSW0RD --data-binary @/tmp/xcc/lnvgy_fw_xcc_cdi338d-2.70_anyos_noarch.uxz https://192.168.1.126:443/fwupdate

The following sample JSON response is returned.

{
   "Id" : "a274a218-58bc-4100-9ec3-6843dfaa486c",
   "Messages" : [],
   "TaskState" : "New",
   "@odata.etag" : "\"1577227530316\"",
   "@odata.id" : "/redfish/v1/TaskService/Tasks/a274a218-58bc-4100-9ec3-6843dfaa486c",
   "PercentComplete" : 0,
   "@odata.type" : "#Task.v1_4_1.Task",
   "StartTime" : "2019-12-24T22:45:30+00:00",
   "Description" : "This resource represents a task for a Redfish implementation.",
   "Name" : "Task a274a218-58bc-4100-9ec3-6843dfaa486c",
   "HidePayload" : true,
   "TaskMonitor" : "/redfish/v1/TaskService/d3883fd4-ed0b-45dc-8c21-f7ad45f81c5d"
}

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 ef05579b-380c-4f23-a20d-d890073fb588)

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

{
   "Id" : "ef05579b-380c-4f23-a20d-d890073fb588",
   "Messages" : [
      {
         "MessageArgs" : [
            "ef05579b-380c-4f23-a20d-d890073fb588",
            "31"
         ],
         "Resolution" : "None.",
         "Message" : "The task with id ef05579b-380c-4f23-a20d-d890073fb588 has changed to progress 31 percent complete.",
         "@odata.type" : "#Message.v1_0_7.Message",
         "MessageId" : "TaskEvent.1.0.TaskProgressChanged",
         "Severity" : "OK"
      },
      {
         "MessageArgs" : [
            "0"
         ],
         "Resolution" : "None",
         "Message" : "Verify 0 percent complete.",
         "@odata.type" : "#Message.v1_0_7.Message",
         "Severity" : "OK",
         "MessageId" : "LenovoFirmwareUpdateRegistry.1.0.UpdateVerifyInProgress"
      }
   ],
   "TaskState" : "Running",
   "@odata.etag" : "\"1577225350164\"",
   "@odata.id" : "/redfish/v1/TaskService/Tasks/ef05579b-380c-4f23-a20d-d890073fb588",
   "PercentComplete" : 31,
   "@odata.type" : "#Task.v1_4_1.Task",
   "StartTime" : "2019-12-24T22:09:02+00:00",
   "Description" : "This resource represents a task for a Redfish implementation.",
   "Name" : "Task ef05579b-380c-4f23-a20d-d890073fb588",
   "HidePayload" : true,
   "TaskMonitor" : "/redfish/v1/TaskService/bf3cd02d-a77e-4ad4-8df8-f00802fc40e0"
}

The 2nd check, task overall progress 58%. It is applying the image.

{
   "Id" : "ef05579b-380c-4f23-a20d-d890073fb588",
   "Messages" : [
      {
         "MessageArgs" : [
            "ef05579b-380c-4f23-a20d-d890073fb588",
            "58"
         ],
         "Resolution" : "None.",
         "Message" : "The task with id ef05579b-380c-4f23-a20d-d890073fb588 has changed to progress 58 percent complete.",
         "@odata.type" : "#Message.v1_0_7.Message",
         "MessageId" : "TaskEvent.1.0.TaskProgressChanged",
         "Severity" : "OK"
      },
      {
         "MessageArgs" : [
            "1",
            "/redfish/v1/UpdateService/FirmwareInventory/UEFI",
            "UEFI-IVE1-6",
            "48M-2.41",
            "Unknown"
         ],
         "Resolution" : "None",
         "Message" : "Assignment 1: Resource /redfish/v1/UpdateService/FirmwareInventory/UEFI SoftwareID UEFI-IVE1-6 Version 48M-2.41 to Version Unknown.",
         "@odata.type" : "#Message.v1_0_7.Message",
         "MessageId" : "LenovoFirmwareUpdateRegistry.1.0.UpdateAssignment",
         "Severity" : "OK"
      },
      {
         "MessageArgs" : [
            "1",
            "36"
         ],
         "Resolution" : "None",
         "Message" : "Assignment 1: Apply 36 percent complete.",
         "@odata.type" : "#Message.v1_0_7.Message",
         "MessageId" : "LenovoFirmwareUpdateRegistry.1.0.PayloadApplyInProgress",
         "Severity" : "OK"
      }
   ],
   "TaskState" : "Running",
   "@odata.etag" : "\"1577225369708\"",
   "@odata.id" : "/redfish/v1/TaskService/Tasks/ef05579b-380c-4f23-a20d-d890073fb588",
   "PercentComplete" : 58,
   "@odata.type" : "#Task.v1_4_1.Task",
   "StartTime" : "2019-12-24T22:09:02+00:00",
   "Description" : "This resource represents a task for a Redfish implementation.",
   "Name" : "Task ef05579b-380c-4f23-a20d-d890073fb588",
   "HidePayload" : true,
   "TaskMonitor" : "/redfish/v1/TaskService/bf3cd02d-a77e-4ad4-8df8-f00802fc40e0"
}

The next check, task overall progress 74%. It is further applying the image.

{
   "Id" : "ef05579b-380c-4f23-a20d-d890073fb588",
   "Messages" : [
      {
         "MessageArgs" : [
            "ef05579b-380c-4f23-a20d-d890073fb588",
            "74"
         ],
         "Resolution" : "None.",
         "Message" : "The task with id ef05579b-380c-4f23-a20d-d890073fb588 has changed to progress 74 percent complete.",
         "@odata.type" : "#Message.v1_0_7.Message",
         "MessageId" : "TaskEvent.1.0.TaskProgressChanged",
         "Severity" : "OK"
      },
      {
         "MessageArgs" : [
            "1",
            "/redfish/v1/UpdateService/FirmwareInventory/UEFI",
            "UEFI-IVE1-6",
            "48M-2.41",
            "Unknown"
         ],
         "Resolution" : "None",
         "Message" : "Assignment 1: Resource /redfish/v1/UpdateService/FirmwareInventory/UEFI SoftwareID UEFI-IVE1-6 Version 48M-2.41 to Version Unknown.",
         "@odata.type" : "#Message.v1_0_7.Message",
         "MessageId" : "LenovoFirmwareUpdateRegistry.1.0.UpdateAssignment",
         "Severity" : "OK"
      },
      {
         "MessageArgs" : [
            "1",
            "61"
         ],
         "Resolution" : "None",
         "Message" : "Assignment 1: Apply 61 percent complete.",
         "@odata.type" : "#Message.v1_0_7.Message",
         "MessageId" : "LenovoFirmwareUpdateRegistry.1.0.PayloadApplyInProgress",
         "Severity" : "OK"
      }
   ],
   "TaskState" : "Running",
   "@odata.etag" : "\"1577225376926\"",
   "@odata.id" : "/redfish/v1/TaskService/Tasks/ef05579b-380c-4f23-a20d-d890073fb588",
   "PercentComplete" : 74,
   "@odata.type" : "#Task.v1_4_1.Task",
   "StartTime" : "2019-12-24T22:09:02+00:00",
   "Description" : "This resource represents a task for a Redfish implementation.",
   "Name" : "Task ef05579b-380c-4f23-a20d-d890073fb588",
   "HidePayload" : true,
   "TaskMonitor" : "/redfish/v1/TaskService/bf3cd02d-a77e-4ad4-8df8-f00802fc40e0"
}

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

{
   "Id" : "ef05579b-380c-4f23-a20d-d890073fb588",
   "Messages" : [
      {
         "MessageArgs" : [
            "ef05579b-380c-4f23-a20d-d890073fb588"
         ],
         "Resolution" : "None.",
         "Message" : "The task with id ef05579b-380c-4f23-a20d-d890073fb588 has completed.",
         "@odata.type" : "#Message.v1_0_7.Message",
         "MessageId" : "TaskEvent.1.0.TaskCompletedOK",
         "Severity" : "OK"
      },
      {
         "MessageArgs" : [
            null
         ],
         "Resolution" : "None",
         "Message" : "Successfully Completed Request",
         "@odata.type" : "#Message.v1_0_7.Message",
         "MessageId" : "Base.1.5.Success",
         "Severity" : "OK"
      },
      {
         "MessageArgs" : [
            "1",
            "/redfish/v1/UpdateService/FirmwareInventory/UEFI",
            "UEFI-IVE1-6",
            "48M-2.41",
            "48M-2.41"
         ],
         "Resolution" : "None",
         "Message" : "Assignment 1: Resource /redfish/v1/UpdateService/FirmwareInventory/UEFI SoftwareID UEFI-IVE1-6 Version 48M-2.41 to Version 48M-2.41.",
         "@odata.type" : "#Message.v1_0_7.Message",
         "MessageId" : "LenovoFirmwareUpdateRegistry.1.0.UpdateAssignment",
         "Severity" : "OK"
      },
      {
         "MessageArgs" : [
            "1"
         ],
         "Resolution" : "None",
         "Message" : "Assignment 1: Apply complete",
         "@odata.type" : "#Message.v1_0_7.Message",
         "MessageId" : "LenovoFirmwareUpdateRegistry.1.0.PayloadApplyCompleted",
         "Severity" : "OK"
      }
   ],
   "TaskState" : "Completed",
   "@odata.etag" : "\"1577225382166\"",
   "@odata.id" : "/redfish/v1/TaskService/Tasks/ef05579b-380c-4f23-a20d-d890073fb588",
   "TaskStatus" : "OK",
   "PercentComplete" : 100,
   "@odata.type" : "#Task.v1_4_1.Task",
   "StartTime" : "2019-12-24T22:09:02+00:00",
   "EndTime" : "2019-12-24T22:09:42+00:00",
   "Description" : "This resource represents a task for a Redfish implementation.",
   "Name" : "Task ef05579b-380c-4f23-a20d-d890073fb588",
   "TaskMonitor" : "/redfish/v1/TaskService/bf3cd02d-a77e-4ad4-8df8-f00802fc40e0",
   "HidePayload" : true
}

  • 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.

{
   "Id" : "afaef595-c15e-4085-b985-7c6c10f10812",
   "Messages" : [
      {
         "MessageArgs" : [
            "afaef595-c15e-4085-b985-7c6c10f10812"
         ],
         "Resolution" : "None.",
         "Message" : "The task with id afaef595-c15e-4085-b985-7c6c10f10812 has completed with warnings.",
         "@odata.type" : "#Message.v1_0_7.Message",
         "MessageId" : "TaskEvent.1.0.TaskCompletedWarning",
         "Severity" : "Warning"
      },
      {
         "MessageArgs" : [
            "7",
            "(0007): Error verifying image transferred to IMM applies to this system."
         ],
         "Resolution" : "Resubmit the request. If the problem persists, consider resetting the service.",
         "Message" : "Verify failed, return code=7 - return message: (0007): Error verifying image transferred to IMM applies to this system.",
         "@odata.type" : "#Message.v1_0_7.Message",
         "MessageId" : "LenovoFirmwareUpdateRegistry.1.0.UpdateVerifyFailed",
         "Severity" : "Warning"
      }
   ],
   "TaskState" : "Exception",
   "@odata.etag" : "\"1577224625433\"",
   "@odata.id" : "/redfish/v1/TaskService/Tasks/afaef595-c15e-4085-b985-7c6c10f10812",
   "TaskStatus" : "Warning",
   "PercentComplete" : 31,
   "@odata.type" : "#Task.v1_4_1.Task",
   "StartTime" : "2019-12-24T21:56:55+00:00",
   "EndTime" : "2019-12-24T21:57:05+00:00",
   "Description" : "This resource represents a task for a Redfish implementation.",
   "Name" : "Task afaef595-c15e-4085-b985-7c6c10f10812",
   "TaskMonitor" : "/redfish/v1/TaskService/5254c31b-1491-40cd-bd94-cb7d9639b5d4",
   "HidePayload" : true
}

XCC keeps a completed/exceptional task resource for status check. Client may access the task monitor resource (the TaskMonitor reference returned in step 3), and XCC removes the corresponding tasks.

  • 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
}