Redfish Update Service

This document describes the Redfish Update Service routes in tlBMC, primarily handled by update_service.cc. This service is key for firmware updates and related actions.

Enablement

The Update Service and its routes are active if the install_module is enabled in the Central Configuration.

The configuration flag is checked in all_routes.cc:

  if (GetTlbmcConfig().install_module().enabled()) {
    task_service::RegisterRoutes(app, root_path);
    update_service::RegisterRoutes(app, root_path);
    redfish_authorization::RegisterRoutes(app, root_path);
  }

Main Service Endpoint

URL: /redfish/v1/UpdateService
Handler: HandleUpdateService
Method: GET
Description: Provides the main entry point for the Update Service. It links to:
- Firmware Inventory: /redfish/v1/UpdateService/FirmwareInventory
- Multipart HTTP Push URI: /redfish/v1/UpdateService/MultipartUpdate/ (for uploading firmware packages)
- Simple Update Action: /redfish/v1/UpdateService/Actions/UpdateService.SimpleUpdate
- OEM Actions:
  - Google.InstallOfflineNodeEntity
  - Google.InstallHostInstallManifest
  - Google.WipeRwfs
  - Google.ReformatEmmc
- OEM Resources / Properties:
  - Debug Logs: /redfish/v1/UpdateService/Oem/Google/DebugLogs
  - Offline Node Entity Base64: /redfish/v1/UpdateService/Oem/Google/OfflineNodeEntityBase64 (exposed as a property)
  - Host Install Manifest: /redfish/v1/UpdateService/Oem/Google/HostInstallManifest (exposed as a property)
  - Authorization Config: /redfish/v1/UpdateService/Oem/Google/AuthorizationConfig
  - Authorization Privilege Registry: /redfish/v1/UpdateService/Oem/Google/AuthorizationPrivilegeRegistry

Redfish Output Example

The following JSON snippet demonstrates a sample Redfish representation of the UpdateService resource (with specific platform identifiers redacted) as exposed over HTTP GET requests:

{
  "@odata.id": "/redfish/v1/UpdateService",
  "@odata.type": "#UpdateService.v1_8_0.UpdateService",
  "Actions": {
    "#UpdateService.SimpleUpdate": {
      "@Redfish.ActionInfo": "/redfish/v1/UpdateService/SimpleUpdateActionInfo",
      "target": "/redfish/v1/UpdateService/Actions/UpdateService.SimpleUpdate"
    },
    "Oem": {
      "#Google.InstallHostInstallManifest": {
        "@Redfish.ActionInfo": "/redfish/v1/UpdateService/Oem/Google/InstallHostInstallManifestActionInfo",
        "target": "/redfish/v1/UpdateService/Actions/Oem/Google.InstallHostInstallManifest"
      },
      "#Google.InstallOfflineNodeEntity": {
        "@Redfish.ActionInfo": "/redfish/v1/UpdateService/Oem/Google/InstallOfflineNodeEntityActionInfo",
        "target": "/redfish/v1/UpdateService/Actions/Oem/Google.InstallOfflineNodeEntity"
      },
      "#Google.ReformatEmmc": {
        "target": "/redfish/v1/UpdateService/Actions/Oem/Google.ReformatEmmc"
      },
      "#Google.WipeRwfs": {
        "target": "/redfish/v1/UpdateService/Actions/Oem/Google.WipeRwfs"
      }
    }
  },
  "FirmwareInventory": {
    "@odata.id": "/redfish/v1/UpdateService/FirmwareInventory"
  },
  "Id": "UpdateService",
  "MultipartHttpPushUri": "/redfish/v1/UpdateService/MultipartUpdate/",
  "Name": "Update Service",
  "Oem": {
    "Google": {
      "AuthorizationConfig": {
        "@odata.id": "/redfish/v1/UpdateService/Oem/Google/AuthorizationConfig"
      },
      "AuthorizationPrivilegeRegistry": {
        "@odata.id": "/redfish/v1/UpdateService/Oem/Google/AuthorizationPrivilegeRegistry"
      },
      "DebugLogs": {
        "@odata.id": "/redfish/v1/UpdateService/Oem/Google/DebugLogs"
      },
      "HostInstallManifest": {},
      "OfflineNodeEntityBase64": ""
    }
  },
  "ServiceEnabled": true
}

Firmware Inventory

URL: /redfish/v1/UpdateService/FirmwareInventory
Handler: HandleFirmwareInventory
Method: GET
Description: Collection of software inventory items representing firmware. It scans the run/install/inventory/ directory (under the root path) for subdirectories containing inventory.json files.
URL: /redfish/v1/UpdateService/FirmwareInventory/{MemberId}
Handler: HandleFirmwareInventoryMember
Method: GET
Description: Details of a specific firmware component. The content is read from run/install/inventory/{MemberId}/inventory.json. Includes Version, Description, and OEM Component Status (/Oem/Google/ComponentStatus).

Firmware Update Actions

Firmware update actions are gated by the store's ownership configuration. If IsFirmwareUpdateable() returns false, these endpoints return a Forbidden (403) response.

Multipart Update

URL: /redfish/v1/UpdateService/MultipartUpdate/
Handler: internal::HandleMultipartUpdate
Method: POST
Description: Uploads firmware bundles using simulated HTTP multipart form data.
- The uploaded file is temporarily stored and then moved to mnt/luks-mmcblk0_fs/firmware_bundle.tar.gz.
- Hash validation is performed if headers Multipart-SHA256-ClientSide and Multipart-SHA256-ServerSide are present.
- It triggers the install-service.service systemd unit asynchronously.
- Returns an Accepted (202) response pointing to the Task Service: /redfish/v1/TaskService/Tasks/FirmwareBundleUpdate.

Simple Update

URL: /redfish/v1/UpdateService/Actions/UpdateService.SimpleUpdate/
Handler: internal::HandleSimpleUpdate
Method: POST
Description: Triggers a firmware update from a remote URI.
- Accepts a JSON body with ImageURI (required) and TransferProtocol (optional, “HTTP” or “HTTPS”).
- Spawns a thread to download the file to /mnt/luks-mmcblk0_fs/firmware_bundle.tar.gz and then triggers install-service.service.
- Returns an Accepted (202) response pointing to the Task Service: /redfish/v1/TaskService/Tasks/FirmwareBundleDownload.
- Progress is written to run/install/download_task.json.
URL: /redfish/v1/UpdateService/SimpleUpdateActionInfo/
Handler: HandleSimpleUpdateActionInfo
Method: GET
Description: Action info for Simple Update.

OEM Actions (Google)

Install Offline Node Entity

Action URL: /redfish/v1/UpdateService/Actions/Oem/Google.InstallOfflineNodeEntity
Handler: HandleInstallOfflineNodeEntity
Method: POST
Action Info URL: /redfish/v1/UpdateService/Oem/Google/InstallOfflineNodeEntityActionInfo (GET)
Description: Accepts a JSON body containing Base64EncodedContent.
- Decodes the content and parses it as production_msv.node_entities_proto.OfflineNodeEntityInformation.
- Validates that machine_name in the resolved config is not empty and is under 27 characters.
- Writes the decoded content to var/google/googlemachineidentity/live/offline_node_entities.pb.

Install Host Install Manifest

Action URL: /redfish/v1/UpdateService/Actions/Oem/Google.InstallHostInstallManifest
Handler: HandleInstallHostInstallManifest
Method: POST
Action Info URL: /redfish/v1/UpdateService/Oem/Google/InstallHostInstallManifestActionInfo (GET)
Description: Accepts a JSON body and writes the raw request body to run/host_install_manifest.json.

Wipe RWFS

Action URL: /redfish/v1/UpdateService/Actions/Oem/Google.WipeRwfs
Handler: internal::HandleWipeRwfs
Method: POST
Description:
[!WARNING]
Do not use this action. Prefer the unified wipe API at /redfish/v1/Managers/bmc/Actions/Oem/Google.Wipe
Example Replacement Payload:
```
POST /redfish/v1/Managers/bmc/Actions/Oem/Google.Wipe
{
  "WipeBmcRwfs": true
}
```
Writes an empty file to var/google/do-rwfs-purge to flag that the read-write filesystem should be wiped on the next boot.

Reformat eMMC

Action URL: /redfish/v1/UpdateService/Actions/Oem/Google.ReformatEmmc
Handler: internal::HandleReformatEmmc
Method: POST
Description:
[!WARNING]
Do not use this action. Prefer the unified wipe API at /redfish/v1/Managers/bmc/Actions/Oem/Google.Wipe
Example Replacement Payload:
```
POST /redfish/v1/Managers/bmc/Actions/Oem/Google.Wipe
{
  "WipeBmcNssAndWipeDioriteNss": true
}
```
Sends a SIGUSR1 signal to psdmd.service (systemctl kill --signal=SIGUSR1 psdmd.service) to trigger an asynchronous eMMC reformat.

OEM Resources and Properties (Google)

Debug Logs

URL: /redfish/v1/UpdateService/Oem/Google/DebugLogs
Handler: internal::HandleDebugLogs
Method: GET
Description: Starts collect-debug-log.service systemd unit and returns the JSON content from run/install/debug_log.json.

Offline Node Entity Base64 (Property)

Property: /Oem/Google/OfflineNodeEntityBase64 (in GET /redfish/v1/UpdateService)
Description: Returns the Base64-encoded content of the file var/google/googlemachineidentity/live/offline_node_entities.pb.

Host Install Manifest (Property)

Property: /Oem/Google/HostInstallManifest (in GET /redfish/v1/UpdateService)
Description: Returns the JSON parsed content of run/host_install_manifest.json.

Firmware Update Gating Logic

The firmware update capability is gated by the store's ownership configuration via IsFirmwareUpdateable().

StoreImpl::IsFirmwareUpdateable() checks if a CredentialManager is instantiated.
If no CredentialManager exists (e.g. TrustBundleInstallModule is disabled), firmware update is allowed by default (true).
If CredentialManager exists, it delegates to CredentialManager::IsFirmwareUpdateable().
CredentialManager::IsFirmwareUpdateable() checks owner_verification_cert_configuration_.
- If no owner verification configuration is present, it returns true.
- Otherwise, it returns the value of fw_update_enabled() from the configuration.