Files
rollcall/cmd/rollcall/redfish_fwplans.go
T
Ilker ManapandClaude Opus 5.5 b01d8e2b4d
CI / agent (push) Successful in 3s
CI / site (push) Successful in 2s
CI / go (push) Successful in 39s
Firmware updates over Redfish, per vendor
A firmware repository on the region (firmware_dir, served under
/firmware/<id>/<file>, cached by rack controllers for BMCs to pull),
each machine's firmware inventory (FirmwareInventory, classified into
bios/bmc/nic/raid/cpld/psu/drive), and update jobs (kind "firmware")
that the region drives with short rack commands: fw-start hands the
package over, fw-poll watches the task (tolerating a BMC that restarts),
fw-finish releases what was claimed, fw-inventory verifies the version.
Running updates resume after a region restart; they cannot be cancelled
once the BMC has the package.

Standard methods (multipart, SimpleUpdate pull, HttpPushUri) with known
Content-Length, plus vendor plans from their documentation or their own
tools: Dell MultipartUpload (OnReset), HPE SimpleUpdate with .fwpkg
extracted at import, Lenovo /mfwupdate with HttpPushUriTargetsBusy,
Supermicro /upload with targets and preserve options, GIGABYTE/AMI/
ASRock Rack /upload with OemParameters ImageType, OpenBMC
update-multipart, xFusion upload to /tmp/web then SimpleUpdate, KAYTUS
upload then OEM SimpleUpdate with fixed tasks, Fujitsu iRMC OEM actions;
Cisco CIMC is refused clearly (SCP only). fw_params and fw_method on
the BMC record override a plan.

CLI rollcall firmware list|import|rm|show|update, API, a Firmware tab
and a repository card in the UI. The lab Redfish emulator gains an
UpdateService (BMC applies at once, BIOS at the next reset).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-29 19:22:01 +01:00

274 lines
14 KiB
Go

package main
// Firmware update plans per vendor: the request each one documents for a
// component. Sources are on each entry; "oss" ones come from the vendor's own
// tools (Ansible collections, PowerShell modules, SDKs) where its API guide is
// not public. An operator can replace a plan's UpdateParameters with
// fw_params={...} on the BMC record, or skip the plan with fw_method=.
import (
"errors"
"fmt"
"path"
"strings"
)
type fwVendor struct {
plan func(fwPlanCtx) (*fwRequest, error)
methods []string
claims bool
unsupported string
formats []string
notes string
sources []string
}
var fwVendors = map[string]fwVendor{
"idrac": {
// MultipartUpload; older iDRAC 9 without it pulls with SimpleUpdate.
// OnReset by default: BIOS-type jobs wait for a reboot anyway, and an
// iDRAC or CPLD update must not surprise anyone.
plan: func(x fwPlanCtx) (*fwRequest, error) {
apply := x.applyOr("OnReset")
if x.Caps.multipart != "" {
return &fwRequest{Method: "multipart", URI: x.Caps.multipart,
Params: obj{"Targets": []string{}, "@Redfish.OperationApplyTime": apply, "Oem": obj{}}}, nil
}
if x.Caps.simple != "" {
return &fwRequest{Method: "simple", URI: x.Caps.simple, Params: simpleBody(x, obj{"@Redfish.OperationApplyTime": apply})}, nil
}
return nil, errors.New("this iDRAC offers neither MultipartHttpPushUri nor SimpleUpdate")
},
formats: []string{".exe", ".d9", ".d7", ".pm"},
notes: "Dell Update Packages (Windows .EXE). BIOS, RAID, NIC jobs apply at the next reboot (-reboot); iDRAC, Diags apply by themselves; a CPLD update does a virtual A/C cycle.",
sources: []string{
"https://github.com/dell/iDRAC-Redfish-Scripting/blob/master/Redfish%20Python/DeviceFirmwareMultipartUploadREDFISH.py",
"https://github.com/dell/iDRAC-Redfish-Scripting/blob/master/Redfish%20Python/DeviceFirmwareSimpleUpdateTransferProtocolREDFISH.py",
},
},
"ilo": {
// SimpleUpdate over HTTP(S) flashes iLO .bin and UEFI .signed.flash;
// a Smart Component (.fwpkg) answers 200 and flashes nothing, so
// import extracts the flashable file from it.
plan: func(x fwPlanCtx) (*fwRequest, error) {
if x.Caps.simple == "" {
return nil, errors.New("this iLO offers no SimpleUpdate")
}
return &fwRequest{Method: "simple", URI: x.Caps.simple, Params: obj{"ImageURI": x.URL}}, nil
},
formats: []string{".bin", ".signed.flash", ".flash", ".fwpkg"},
notes: "iLO firmware flashes at once (iLO restarts); UEFI/BIOS is staged and flashed at the next reboot (-reboot). Components only a runtime agent can flash (some NICs) need SUM/iSUT in the OS. Downgrades follow the iLO downgrade policy.",
sources: []string{
"https://servermanagementportal.ext.hpe.com/docs/references_and_material/blogposts/firmware_updates/part3/firmware_update_part3",
"https://servermanagementportal.ext.hpe.com/docs/redfishservices/ilos/supplementdocuments/updateservice/",
},
},
"xcc": {
// /mfwupdate, after taking the push service (HttpPushUriTargetsBusy).
plan: func(x fwPlanCtx) (*fwRequest, error) {
params := obj{"Targets": []string{}}
if x.Apply != "" {
params["@Redfish.OperationApplyTime"] = x.Apply
}
if x.Caps.multipart != "" {
return &fwRequest{Method: "multipart", URI: x.Caps.multipart, Params: params, Claim: true}, nil
}
if x.Caps.push != "" {
return &fwRequest{Method: "push", URI: x.Caps.push, Claim: true}, nil
}
return nil, errors.New("this XCC offers no push update URI")
},
claims: true,
formats: []string{".uxz", ".zip", ".bin"},
notes: "Update XCC before UEFI (Lenovo). One push at a time; the busy flag is released after the update.",
sources: []string{
"https://pubs.lenovo.com/xcc-restapi/simple_update_firmware_post_multi_httppush",
"https://pubs.lenovo.com/xcc2-restapi/prop_firmware_update_service_get",
"https://pubs.lenovo.com/xcc/updating_firmware_overview",
},
},
"supermicro": {
// /UpdateService/upload with the documented targets and preserve options.
plan: func(x fwPlanCtx) (*fwRequest, error) {
uri := orDefault(x.Caps.multipart, "/redfish/v1/UpdateService/upload")
apply := x.applyOr("Immediate")
var params obj
switch x.Component {
case "bios":
params = obj{"Targets": []string{"/redfish/v1/Systems/1/Bios"}, "@Redfish.OperationApplyTime": apply,
"Oem": obj{"Supermicro": obj{"BIOS": obj{"PreserveME": true, "PreserveNVRAM": true, "PreserveSMBIOS": true, "BackupBIOS": false}}}}
case "bmc":
params = obj{"Targets": []string{"/redfish/v1/Managers/1"}, "@Redfish.OperationApplyTime": apply,
"Oem": obj{"Supermicro": obj{"BMC": obj{"PreserveCfg": true, "PreserveSdr": true, "PreserveSsl": true, "BackupBMC": true}}}}
case "cpld":
id := ""
for _, i := range x.Inventory {
if strings.HasPrefix(i, "Motherboard_CPLD_") && id == "" {
id = i
}
}
if id == "" {
return nil, errors.New("the BMC lists no Motherboard_CPLD_* firmware")
}
params = obj{"Targets": []string{"/redfish/v1/UpdateService/FirmwareInventory/" + id}, "@Redfish.OperationApplyTime": apply}
default: // NIC, storage AOC, PSU: the BMC picks the device (SFT-DCMS-SINGLE licence)
params = obj{"Targets": []string{}, "@Redfish.OperationApplyTime": apply}
}
return &fwRequest{Method: "multipart", URI: uri, Params: params}, nil
},
notes: "A BIOS update powers the host off first. Gen 12/13 boards take other BIOS preserve options (PreserveOA, PreserveSETUPCONF, ...): set fw_params on the BMC if the BMC refuses these. Redfish updates need the SFT-OOB-LIC or SFT-DCMS-SINGLE licence; NIC/storage/PSU need DCMS. A CPLD update resets the BMC.",
sources: []string{
"https://www.supermicro.com/manuals/other/RedfishUserGuide.pdf",
"https://github.com/bmc-toolbox/bmclib/blob/main/providers/supermicro/x12.go",
},
},
"gigabyte": {plan: amiPlan, formats: []string{".hpm", ".rcu", ".ima_enc", ".ima", ".rbu", ".bin"}, notes: amiNotes, sources: []string{"https://download.gigabyte.com/FileList/Manual/server_manual_redfish_v1.11.0.pdf", "GIGABYTE Firmware Upgrade Guide v0.04 (2022)"}},
"ami": {plan: amiPlan, notes: amiNotes, sources: []string{"https://download2.mitaccomputing.com/pub/doc/MiTAC_AST2600_Redfish_API_Doc_v.1_051024.pdf", "https://support.blackcoretech.com/support/solutions/articles/70000680445-update-bios-bmc-via-redfish-multipart-push"}},
"asrockrack": {plan: amiPlan, notes: amiNotes + " ASRock Rack's own Redfish firmware notes could not be read: this is the AMI MegaRAC request, check it on one machine first.", sources: []string{"https://download.asrock.com/TSD/SMU/Manual/ASRock%20Rack%20Server%20Management_v2.8.0.pdf"}},
"openbmc": {
// update-multipart; the BMC image applies at once (it reboots), the rest OnReset.
plan: func(x fwPlanCtx) (*fwRequest, error) {
params := obj{"Targets": []string{}}
if x.Component == "bmc" {
params = obj{"Targets": []string{"/redfish/v1/Managers/bmc"}, "@Redfish.OperationApplyTime": x.applyOr("Immediate")}
} else if x.Apply != "" {
params["@Redfish.OperationApplyTime"] = x.Apply
}
if x.Caps.multipart != "" {
return &fwRequest{Method: "multipart", URI: x.Caps.multipart, Params: params}, nil
}
if x.Caps.push != "" && x.Component == "bmc" {
return &fwRequest{Method: "push", URI: x.Caps.push}, nil
}
return nil, errors.New("this OpenBMC offers no multipart update (SimpleUpdate is off in bmcweb by default)")
},
formats: []string{".tar"},
notes: "Signed image tarballs whose MANIFEST MachineName matches the BMC.",
sources: []string{"https://github.com/openbmc/bmcweb/blob/master/redfish-core/lib/update_service.hpp", "https://github.com/openbmc/docs/blob/master/REDFISH-cheatsheet.md"},
},
"xfusion": {
// upload to the BMC's /tmp/web, then SimpleUpdate naming the file
plan: func(x fwPlanCtx) (*fwRequest, error) {
if x.Component != "bmc" && x.Component != "bios" && x.Component != "cpld" {
return nil, fmt.Errorf("iBMC updates BMC, BIOS and CPLD out of band; %s firmware goes through Smart Provisioning in-band (not supported)", x.Component)
}
if x.Caps.simple == "" {
return nil, errors.New("this iBMC offers no SimpleUpdate")
}
return &fwRequest{Method: "multipart", URI: "/redfish/v1/UpdateService/FirmwareInventory", NoParams: true, Field: "file",
Then: &fwRequest{Method: "simple", URI: x.Caps.simple, Params: obj{"ImageURI": "/tmp/web/" + path.Base(x.File)}}}, nil
},
formats: []string{".hpm"},
notes: "The BMC restarts after a BMC update.",
sources: []string{
"https://github.com/Open-xFusion/Server_Plugin_Ansible/blob/HEAD/ibmc_ansible/ibmc_redfish_api/api_manage_file.py",
"https://github.com/Open-xFusion/Server_Plugin_Ansible/blob/HEAD/ibmc_ansible/ibmc_redfish_api/api_outband_fw_update.py",
},
},
"kaytus": {
// upload (with the BMC password), then an OEM SimpleUpdate; the tasks have fixed names
plan: func(x fwPlanCtx) (*fwRequest, error) {
oem := obj{"PreserveConf": true}
var tasks []string
switch x.Component {
case "bmc":
oem["FlashItem"], tasks = "OpenBMC_ENC", []string{"/redfish/v1/TaskService/Tasks/BMC"}
case "bios":
oem["FlashItem"], oem["BiosFlash"] = "BIOS", "Both"
tasks = []string{"/redfish/v1/TaskService/Tasks/BIOS0", "/redfish/v1/TaskService/Tasks/BIOS1"}
default:
return nil, fmt.Errorf("KAYTUS: BMC and BIOS only (not %s)", x.Component)
}
return &fwRequest{Method: "multipart", URI: "/redfish/v1/UpdateService/FirmwareInventory", NoParams: true, Field: "fwimage",
Form: map[string]string{"CurrentPassword": x.Password, "EncryptFlag": "False"}, FailText: "Verification Failed",
Then: &fwRequest{Method: "simple", URI: orDefault(x.Caps.simple, "/redfish/v1/UpdateService/Actions/UpdateService.SimpleUpdate"), Params: obj{"Oem": obj{"Public": oem}}},
Tasks: tasks}, nil
},
formats: []string{".hpm", ".bin"},
notes: "No public Redfish guide: this is what KAYTUS's own SDK (ksManage) does on X3-generation BMCs; older generations use a non-Redfish API. A BIOS update with the host on waits for a power cycle (-reboot); the BMC restarts after a BMC update.",
sources: []string{"https://github.com/KSManageOSS/ksManage/blob/HEAD/ksmanage_sdk/interface/CommonX3.py", "https://github.com/ieisystem/kaytus.ksmanage"},
},
"irmc": {
// OEM actions per component, file in the "data" part
plan: func(x fwPlanCtx) (*fwRequest, error) {
p := "Fsas" // FTS on S5/S6 (Vendor ts_fujitsu or none), Fsas on newer firmware
if x.Vendor == "" || strings.EqualFold(x.Vendor, "ts_fujitsu") {
p = "FTS"
}
switch x.Component {
case "bmc":
return &fwRequest{Method: "multipart", URI: "/redfish/v1/Managers/iRMC/Actions/" + p + "Manager.FWUpdate",
AltURI: "/redfish/v1/Managers/iRMC/Actions/Oem/" + p + "Manager.FWUpdate", NoParams: true, Field: "data"}, nil
case "bios":
return &fwRequest{Method: "multipart", URI: "/redfish/v1/Systems/0/Bios/Actions/Oem/" + p + "Bios.BiosUpdate", NoParams: true, Field: "data"}, nil
}
return nil, fmt.Errorf("iRMC: iRMC and BIOS only (not %s)", x.Component)
},
formats: []string{".bin", ".upc"},
notes: "iRMC .bin, BIOS .UPC. With the host on, a BIOS update waits for a reboot (-reboot); the iRMC restarts after its own update.",
sources: []string{"https://github.com/fujitsu/ansible-irmc-integration/blob/HEAD/plugins/modules/irmc_fwbios_update.py", "https://github.com/mmurayama/fujitsu-redfish-samples/blob/master/scripts/update_irmc_firmware.py"},
},
"cimc": {
unsupported: "Cisco documents CIMC firmware updates over Redfish only as SimpleUpdate pulls over SCP (and HSU/HUU from NFS, CIFS or HTTPS shares); Rollcall serves packages over HTTP",
sources: []string{"https://www.cisco.com/c/en/us/td/docs/unified_computing/ucs/c/sw/api/4_3/b-cisco-ucs-c-series-servers-rest-api-programmer-s-guide-release-4-3.pdf"},
},
}
const amiNotes = "MegaRAC: the BMC restarts after a BMC flash and accepts no logins while flashing; do not use its web UI meanwhile."
// amiPlan: /UpdateService/upload with UpdateParameters (the inventory target)
// and OemParameters (ImageType); .hpm packages have their own targets.
func amiPlan(x fwPlanCtx) (*fwRequest, error) {
hpm := strings.HasSuffix(strings.ToLower(x.File), ".hpm")
var target, typ string
switch x.Component {
case "bmc":
if hpm {
target, typ = "BMC", "HPM_BMC"
} else {
target, typ = orDefault(x.first("BMCImage1", "BMC"), "BMC"), "BMC"
}
case "bios":
if hpm {
target, typ = "BIOS2", "HPM_BIOS"
} else {
target, typ = "BIOS", "BIOS"
}
case "cpld":
target, typ = "MB_CPLD1", "MB_CPLD"
default:
return nil, fmt.Errorf("MegaRAC: BMC, BIOS and CPLD (not %s)", x.Component)
}
if len(x.Inventory) > 0 && !x.has(target) {
return nil, fmt.Errorf("the BMC lists no firmware %s (it has %s)", target, strings.Join(x.Inventory, ", "))
}
params := obj{"Targets": []string{"/redfish/v1/UpdateService/FirmwareInventory/" + target}}
if x.Apply != "" {
params["@Redfish.OperationApplyTime"] = x.Apply
}
return &fwRequest{Method: "multipart", URI: orDefault(x.Caps.multipart, "/redfish/v1/UpdateService/upload"), Params: params,
Parts: []fwPart{{Name: "OemParameters", Body: obj{"ImageType": typ}}}}, nil
}
// simpleBody is a SimpleUpdate body for the package URL, plus extra fields.
func simpleBody(x fwPlanCtx, extra obj) obj {
b := obj{"ImageURI": x.URL}
if len(x.Caps.protocols) > 0 {
b["TransferProtocol"] = strings.ToUpper(strings.SplitN(x.URL, "://", 2)[0])
}
for k, v := range extra {
b[k] = v
}
return b
}
func init() {
for i := range redfishProfiles {
p := &redfishProfiles[i]
if v, ok := fwVendors[p.Driver]; ok {
p.FWPlan, p.FWMethods, p.FWClaims, p.FWUnsupported = v.plan, v.methods, v.claims, v.unsupported
p.FWFormats, p.FWNotes, p.FWSources = v.formats, v.notes, v.sources
}
}
}