代码仓
中
更新时间: 2026/11/14
在AtomGit上查看源码

ums(USB Mass Storage) ​

版本信息 ​

项目内容
组件版本1.140.0
首发版本iBMC500 5.15.0
文档作者openUBMC
最后更新2026-10-19

1. 组件概述 ​

1.1 组件简介 ​

ums(USB Mass Storage)是 openUBMC 运维子系统下的应用类微组件,服务名 bmc.kepler.ums,部署配置为 om_priv.service。它基于 USB 大容量存储协议,在 BMC 侧将 SP(SmartProvisioning)/ BMA(板载 iBMA)的 Flash 分区虚拟为 U 盘,使主机 OS 能够像访问本地 U 盘一样与 BMC 进行文件交换,并在此机制之上承载 SP/BMA 固件升级、SP 任务编排、SP Schema 更新、SP 插件管理、OS 部署、SP 诊断等业务。

1.2 解决什么问题 ​

  • 解决 BMC 与主机 OS 之间通过 USB 通道进行大文件、批量文件双向传输的问题,避免依赖网络通道。
  • 解决 SP(SmartProvisioning)、板载 BMA 固件的本地/远程升级问题,包含升级包下载、签名校验、分区写入、版本切换等完整流程。
  • 解决 SP 业务任务(OS 安装、SP 诊断、SP 固件升级)的统一调度与状态上报问题,对外提供 Redfish / IPMI / 资源协作接口。

1.3 核心功能 ​

  • 核心功能一:虚拟 U 盘管理 —— 通过 CreateUms/CloseUms 接口将 SP/BMA Flash 分区映射为虚拟 U 盘并挂载到主机,支持本地与远程两种 U 盘类型、临时与正式两种挂载类型,并在电源关闭或 OS 复位时自动卸载。
  • 核心功能二:U 盘文件读写 —— 通过 ReadFile/WriteFile/GetFileList/CheckFileExist/ClearDirectory 在 BMC 侧按 PathId 访问 U 盘内 SP 业务目录(部署任务、诊断结果、OS 部署、固件升级、RAID 配置、SP 配置/信息/Schema 等)。
  • 核心功能三:SP/BMA 固件升级 —— 支持 Full/Recover/APP/Driver/Auto 多种升级模式,Auto 模式下自动判定是否需要降级为 Recover,支持本地 file:// 与远程 https/sftp/nfs/cifs/scp 协议,支持 CMS 签名校验与 CRL 校验。
  • 核心功能四:SP 任务编排 —— 通过 JobService 下的 SPDiagnose、SPFWUpdate、SPOSInstall 三个 JobFunction 对接 Redfish 任务框架,支持 Run/Cancel/BeforeCreate 生命周期。
  • 核心功能五:SP 插件管理 —— 通过 Install/Delete/IsPluginInstalled/GetPluginInfo 完成扩展插件的安装、卸载、查询,支持队列化安装、签名校验、解压限流。
  • 核心功能六:SP Schema 与版本维护 —— 通过 SP.Schema.Update 更新 SP Redfish Schema,并在升级 SP 后同步刷新版本信息(APPVersion/OSVersion/MajorVersion 等)。

1.4 关键术语表(可选) ​

术语解释
UMSUSB Mass Storage,USB 大容量存储协议,本组件将 Flash 分区虚拟为 U 盘供主机访问
SPSmartProvisioning,主机侧智能部署服务,由本组件负责升级及业务文件下发
BMA板载 iBMA(Baseboard Management Agent),本组件负责其分区挂载与固件升级
PathIdU盘文件读写的目录枚举值,1~13 分别对应不同的 SP 业务目录
CMSCryptographic Message Syntax,用于升级包签名校验
TPCMTrusted Platform Control Module,可信平台控制模块,在位或可信计算使能时禁止 U 盘挂载

1.5 外部交互边界图 ​

2. API 使用说明与示例 ​

2.1 CreateUms(创建虚拟 U 盘) ​

功能说明 ​

将 SP 或 BMA 的 Flash 分区映射为虚拟 U 盘并连接到主机侧 USB 接口,供主机 OS 读写访问。支持临时挂载(Type=0)与正式挂载(Type=1),支持本地 U 盘(Loc=0)与远程 U 盘(Loc=1)。

属性内容
接口名bmc.kepler.Managers.Ums.CreateUms
废弃状态正常可用

参数说明 ​

接口入参顺序为 Loc, Type(Loc 在前,Type 在后),busctl 调用时签名 yy Loc Type。

参数名方向类型描述取值范围
Loc输入U8U 盘类型0:本地 U 盘;1:远程 U 盘
Type输入U8挂载类型0:临时挂载;1:正式挂载;>1 视为非法

返回值与异常 ​

返回值含义触发条件处理建议
0成功U 盘挂载任务创建成功无
-110UMS 被占用OsAccessMode 非 NoAccess,U 盘被主机 OS 占用等待主机释放后重试
异常 PropertyModificationNotSupported参数不支持Type>1 或对象 ID 不含 BMA检查参数与对象路径
异常 IPMICommandCannotExecuteTPCM 限制TPCM 在位或基础可信计算使能关闭可信计算或拔出 TPCM 后重试

应用场景 ​

主机需要在 OS 侧访问 SP/BMA Flash 内的部署文件、诊断结果、升级包时,通过本接口将 Flash 分区虚拟为 U 盘。

限制条件 ​

  • 调用前需确认 TPCM 不在位且基础可信计算未使能。
  • 一次仅允许一个挂载任务,重复调用需等待前序任务完成。
  • 电源关闭或 OS 复位时会自动卸载 U 盘。

调试示例 ​

命令行调试 ​
bash
# busctl 签名 yy Loc Type:Loc=0 本地 U 盘,Type=0 临时挂载
busctl --user call bmc.kepler.ums /bmc/kepler/Managers/1/Ums/BMA bmc.kepler.Managers.Ums CreateUms yy 0 0

2.2 CloseUms(关闭虚拟 U 盘) ​

功能说明 ​

卸载并断开已挂载到主机侧的 SP/BMA 虚拟 U 盘,释放 USB 通道与挂载点。

属性内容
接口名bmc.kepler.Managers.Ums.CloseUms
废弃状态正常可用

参数说明 ​

参数名方向类型描述取值范围
---本接口无输入参数-

返回值与异常 ​

| 返回值 | 含义 | 触发条件 | 处理建议 | | :--- | :--- | :--- | :--- | :--- | | 0 | 成功 | 卸载任务创建成功 | 无 | | 异常 PropertyModificationNotSupported | 不支持 | 对象 ID 不含 BMA 或已有任务运行中 | 等待任务完成或检查对象 |

应用场景 ​

升级任务完成后、主机下电前,或业务侧主动需要回收 U 盘时调用。

限制条件 ​

  • 一次仅允许一个卸载任务,重复调用需等待前序任务完成。
  • 同样受 TPCM/基础可信计算限制。

调试示例 ​

命令行调试 ​
bash
busctl --user call bmc.kepler.ums /bmc/kepler/Managers/1/Ums/BMA bmc.kepler.Managers.Ums CloseUms

2.3 ReadFile(读 U 盘文件) ​

功能说明 ​

按 PathId 读取 U 盘内指定文件的内容,返回文件原始数据。读操作会获取 UMS 传输锁并确认 U 盘未被主机占用。

属性内容
接口名bmc.kepler.Managers.Ums.ReadFile
废弃状态正常可用

参数说明 ​

参数名方向类型描述取值范围
PathId输入U8文件路径 id1~13,对应不同 SP 业务目录
FileName输入String文件名不含 / 与 ..,长度合法
返回输出String文件内容单文件最大 2MB

返回值与异常 ​

| 返回值 | 含义 | 触发条件 | 处理建议 | | :--- | :--- | :--- | :--- | :--- | | 文件内容 | 成功 | 文件读取成功 | 无 | | 空串 | 文件不存在或过大 | 文件不存在或超过 2MB | 检查 PathId/FileName | | 异常 UMSIsExclusivelyUsed | UMS 被占用 | OsAccessMode 非 NoAccess | 等待主机释放 |

应用场景 ​

OM/Redfish 需要读取 SP 部署任务、诊断结果、RAID 配置导出、SP Schema 等业务文件时调用。

限制条件 ​

  • 单文件最大 2MB(UMS_MAX_CFG_FILE_LEN)。
  • 文件名不允许包含路径分隔符或 ..,防止路径穿越。
  • PathId 必须在 ums_trans_path 配置范围内。

调试示例 ​

命令行调试 ​
bash
busctl --user call bmc.kepler.ums /bmc/kepler/Managers/1/Ums/SP bmc.kepler.Managers.Ums ReadFile ys 1 "result.json"

2.4 WriteFile(写 U 盘文件) ​

功能说明 ​

向 U 盘内指定 PathId 目录写入文件内容,并在写入后同步 SP 任务描述文件 sptask.json。

属性内容
接口名bmc.kepler.Managers.Ums.WriteFile
废弃状态正常可用

参数说明 ​

参数名方向类型描述取值范围
PathId输入U8文件路径 id1~13
FileName输入String文件名不含 / 与 ..
Content输入String写入内容单文件最大 2MB

返回值与异常 ​

| 返回值 | 含义 | 触发条件 | 处理建议 | | :--- | :--- | :--- | :--- | :--- | | 0 | 成功 | 写入成功 | 无 | | 异常 UMSIsExclusivelyUsed | UMS 被占用 | OsAccessMode 非 NoAccess | 等待主机释放 |

应用场景 ​

OM 向 SP 下发部署任务、诊断任务、固件升级包元数据时调用。

限制条件 ​

  • 同 ReadFile 的路径与大小限制。
  • 每个目录最大文件数 50(UMS_MAX_FILE_CNT),U 盘利用率上限 95%。

调试示例 ​

命令行调试 ​
bash
busctl --user call bmc.kepler.ums /bmc/kepler/Managers/1/Ums/SP bmc.kepler.Managers.Ums WriteFile yss 3 "osinstall.json" "{...}"

2.5 GetFileList / CheckFileExist / ClearDirectory ​

功能说明 ​

  • GetFileList(PathId):返回指定 PathId 目录下的文件名列表(不含路径)。
  • CheckFileExist(PathId, FileName):判断指定文件是否存在。
  • ClearDirectory(PathId):清空指定 PathId 目录下的所有内容并重置目录大小计数。
属性内容
接口名bmc.kepler.Managers.Ums.GetFileList / CheckFileExist / ClearDirectory
废弃状态正常可用

参数说明 ​

参数名方向类型描述取值范围
PathId输入U8文件路径 id1~13
FileName输入String文件名(仅 CheckFileExist)不含 / 与 ..

返回值与异常 ​

| 返回值 | 含义 | 触发条件 | 处理建议 | | :--- | :--- | :--- | :--- | :--- | | 文件列表 / 布尔 / 0 | 成功 | 操作成功 | 无 | | 异常 UMSIsExclusivelyUsed | UMS 被占用 | OsAccessMode 非 NoAccess | 等待主机释放 |

应用场景 ​

OM 在下发任务前查询目录、确认文件是否就绪,或任务完成后清理目录。

限制条件 ​

  • 同 ReadFile 的路径与挂载状态限制。

调试示例 ​

命令行调试 ​
bash
busctl --user call bmc.kepler.ums /bmc/kepler/Managers/1/Ums/SP bmc.kepler.Managers.Ums GetFileList y 1
busctl --user call bmc.kepler.ums /bmc/kepler/Managers/1/Ums/SP bmc.kepler.Managers.Ums CheckFileExist ys 1 "result.json"
busctl --user call bmc.kepler.ums /bmc/kepler/Managers/1/Ums/SP bmc.kepler.Managers.Ums ClearDirectory y 4

2.6 UpdateSP(升级 SP) ​

功能说明 ​

触发 SP 固件升级。根据 UpdateMode 选择升级策略,Auto 模式下会根据 MajorVersion 变更、分区挂载状态、full.ini/version.json 完整性自动判定是否降级为 Recover 模式。

属性内容
接口名bmc.kepler.Managers.Ums.SP.UpdateSP
废弃状态正常可用

参数说明 ​

参数名方向类型描述取值范围
ImageURI输入String升级文件路径file:///https:///sftp:///nfs:///cifs:///scp://
UpdateMode输入String升级模式Full / Recover / APP / Driver / Auto
ActiveMethod输入String升级生效模式由调用方约定

返回值与异常 ​

| 返回值 | 含义 | 触发条件 | 处理建议 | | :--- | :--- | :--- | :--- | :--- | | task_id | 成功 | 升级任务创建成功 | 通过 Task 资源查询进度 | | 异常 BMCNotSupportedSP | 板型不支持 | FlashDev 不可访问 | 检查板型是否支持 SP | | 异常 UMSIsExclusivelyUsed | UMS 被占用 | OsAccessMode 非 NoAccess | 等待主机释放 | | 异常 UpgradingErr | 重复升级 | 已有升级任务运行中 | 等待当前升级完成 | | 异常 upgrade_uri_illegal(-113) | URI 非法 | ImageURI 格式不匹配 | 检查 URI 协议与后缀 | | 异常 cms_auth_error(-112) | 签名校验失败 | 升级包 CMS 校验不通过 | 检查升级包与签名文件 |

应用场景 ​

通过 Redfish UpdateService 或 IPMI 触发 SP 固件升级,支持本地 ISO 与远程协议。

限制条件 ​

  • 调用前必须确认 OsAccessMode 为 NoAccess。
  • 一次仅允许一个升级任务。
  • 远程协议需先经 FileTransfer 服务挂载成功。

调试示例 ​

命令行调试 ​
bash
busctl --user call bmc.kepler.ums /bmc/kepler/Managers/1/Ums/SP bmc.kepler.Managers.Ums.SP UpdateSP sss "file:///tmp/sp.iso" "Auto" "Immediate"

2.7 UpdateFirmware(升级 SP 固件) ​

功能说明 ​

通过 bmc.kepler.Managers.Ums.SP.UpdateFirmware 升级 SP 固件,与 UpdateSP 共用底层升级流程,但额外支持 ImageCerURI(证书 URI)与 Parameter(参数)。

属性内容
接口名bmc.kepler.Managers.Ums.SP.UpdateFirmware
废弃状态正常可用

参数说明 ​

参数名方向类型描述取值范围
ImageURI输入String升级包路径同 UpdateSP
ImageCerURI输入String证书文件路径同 UpdateSP
Parameter输入String升级参数由调用方约定
ActiveMethod输入String升级生效模式由调用方约定

返回值与异常 ​

同 2.6 节 UpdateSP。

应用场景 ​

Redfish UpdateService 通过 SPFWUpdate JobFunction 调用本接口完成 SP 固件升级。

限制条件 ​

同 2.6 节 UpdateSP。

调试示例 ​

命令行调试 ​
bash
busctl --user call bmc.kepler.ums /bmc/kepler/Managers/1/Ums/SP bmc.kepler.Managers.Ums.SP UpdateFirmware ssss "https://srv/sp.tar.gz" "https://srv/sp.cms" "" "Immediate"

2.8 GetSPStatus(查询 SP 状态) ​

功能说明 ​

返回 SP 当前状态字符串,状态按优先级依次判定:分区表不存在 → 需要升级 → iBMC 需要升级 → OS 已关机 → BIOS 需要升级 → SP 可操作 → SP 工作中。

属性内容
接口名bmc.kepler.Managers.Ums.SP.GetSPStatus
废弃状态正常可用

参数说明 ​

参数名方向类型描述取值范围
---无输入参数-
返回输出StringSP 状态字符串见下表

返回值取值:

状态含义
SPPartitionTableNotExistSP FlashDev 不可访问,分区表不存在
SPNeedsUpdateAPPVersion 无效,需要升级 SP
iBMCNeedsUpdateums.Enable 为 false,iBMC 需要升级
OSIsPoweredOff主机电源为 OFF
BIOSNeedsUpdateums.BiosSupport 为 false,BIOS 需要升级
SPIsOperableSP 与 BMC 心跳未建立,SP 可操作
SPIsWorkingSP 与 BMC 心跳已建立,SP 工作中

返回值与异常 ​

| 返回值 | 含义 | 触发条件 | 处理建议 | | :--- | :--- | :--- | :--- | :--- | | 状态字符串 | 成功 | 正常执行 | 无 | | 空串 | 电源状态未知 | 电源状态读取失败 | 检查 FruCtrl 服务 |

应用场景 ​

OM/Redfish 在执行 SP 业务前查询 SP 是否就绪、是否需要升级。

限制条件 ​

无特殊限制。

调试示例 ​

命令行调试 ​
bash
busctl --user get-property bmc.kepler.ums /bmc/kepler/Managers/1/Ums/SP bmc.kepler.Managers.Ums.SP SPStatus
busctl --user call bmc.kepler.ums /bmc/kepler/Managers/1/Ums/SP bmc.kepler.Managers.Ums.SP GetSPStatus

2.9 GetSPResult / GetSPServiceSignature / GetOSInstallPara ​

功能说明 ​

  • GetSPResult:返回 SP 任务执行结果(JSON),状态字段取值 Idle/Init/Deploying/Finished/Timeout。
  • GetSPServiceSignature:返回 SP 服务的验签方法(JSON),默认 {"PGP":{"Suffix": "asc"}}。
  • GetOSInstallPara:返回 SP OS 安装参数文件源。
属性内容
接口名bmc.kepler.Managers.Ums.SP.GetSPResult / GetSPServiceSignature / GetOSInstallPara
废弃状态正常可用

参数说明 ​

参数名方向类型描述取值范围
---无输入参数-
返回输出StringJSON 字符串见功能说明

返回值与异常 ​

| 返回值 | 含义 | 触发条件 | 处理建议 | | :--- | :--- | :--- | :--- | :--- | | JSON 字符串 | 成功 | 读取成功 | 无 | | 异常 InternalError | 内部错误 | UMS 挂载失败或文件解析失败 | 检查 SP 状态与文件 | | 异常 ResourceInUse | 资源占用 | 传输锁获取失败 | 等待释放后重试 |

应用场景 ​

Redfish Sms/{n}/Managers/1/SPService/SPResult/1 接口透传 SP 任务结果;OM 通过 GetSPServiceSignature 确认签名格式。

限制条件 ​

  • 同 ReadFile 的挂载与锁限制。

调试示例 ​

命令行调试 ​
bash
busctl --user call bmc.kepler.ums /bmc/kepler/Managers/1/Ums/SP bmc.kepler.Managers.Ums.SP GetSPResult
busctl --user call bmc.kepler.ums /bmc/kepler/Managers/1/Ums/SP bmc.kepler.Managers.Ums.SP GetSPServiceSignature
busctl --user call bmc.kepler.ums /bmc/kepler/Managers/1/Ums/SP bmc.kepler.Managers.Ums.SP GetOSInstallPara

2.10 SP 插件管理(Install / Delete / IsPluginInstalled / GetPluginInfo) ​

功能说明 ​

  • Install(PackageURI, SignatureFileURI):安装 SP 插件,支持队列化安装、签名校验、解压限流,单个安装包最大 900M,所有插件最多 1800M。
  • Delete(PluginName):删除已安装的 SP 插件。
  • IsPluginInstalled(PluginName):查询插件是否已安装。
  • GetPluginInfo(PluginName):获取插件详细信息。
属性内容
接口名bmc.kepler.Managers.Ums.SP.Plugin.Install / Delete / IsPluginInstalled / GetPluginInfo
废弃状态正常可用

参数说明 ​

参数名方向类型描述取值范围
PackageURI输入String插件包来源同 UpdateSP 的 URI 协议
SignatureFileURI输入String签名文件来源同上
PluginName输入String插件名非空字符串

返回值与异常 ​

| 返回值 | 含义 | 触发条件 | 处理建议 | | :--- | :--- | :--- | :--- | :--- | | task_id / 0 / 布尔 / 信息 | 成功 | 操作成功 | 无 | | 异常 cms_auth_error(-112) | 签名校验失败 | 插件签名校验不通过 | 检查插件包与签名 | | 异常 ResourceInUse | 队列已满 | 待安装队列超过 10 个 | 等待队列空闲 |

应用场景 ​

通过 Redfish 扩展 SP 能力,安装伙伴厂商提供的扩展插件。

限制条件 ​

  • 安装队列容量 10,单个插件最多 32 个组件,压缩包最大文件数 512。
  • 安装超时 24 小时,单文件下载超时 4 小时,解压超时 900 秒。
  • U 盘利用率上限 95%。

调试示例 ​

命令行调试 ​
bash
busctl --user call bmc.kepler.ums /bmc/kepler/Managers/1/Ums/SP bmc.kepler.Managers.Ums.SP.Plugin Install ss "https://srv/plugin.tar.gz" "https://srv/plugin.cms"
busctl --user call bmc.kepler.ums /bmc/kepler/Managers/1/Ums/SP bmc.kepler.Managers.Ums.SP.Plugin IsPluginInstalled s "myplugin"

2.11 SP.Schema.Update(更新 SP Redfish Schema) ​

功能说明 ​

更新 SP Redfish Schema 文件,解压后写入 /data/sp/spforbmc/spschema/,并同步刷新动态 mapping_config。

属性内容
接口名bmc.kepler.Managers.Ums.SP.Schema.Update
废弃状态正常可用

参数说明 ​

参数名方向类型描述取值范围
ChecksumValue输入String校验值由调用方提供
FileName输入StringSchema 文件名非空字符串

返回值与异常 ​

| 返回值 | 含义 | 触发条件 | 处理建议 | | :--- | :--- | :--- | :--- | :--- | | 0 | 成功 | 更新成功 | 无 | | 异常 InternalError | 内部错误 | 文件校验或解压失败 | 检查文件完整性 |

应用场景 ​

Redfish 通过 SP Schema 接口下发新的 Schema 包,更新 SP 服务支持的资源模型。

限制条件 ​

  • 压缩包解压后单文件最大 10M(PKG_MAX_SIZE),文件数最大 512(PKG_MAX_FILE_NUM)。
  • Schema 解压临时目录为 /dev/shm/schema/spschema/,相关常量 SP_SCHEMA_MAX_PATH_NUM=255(路径数量上限,当前代码未引用,保留作为预留约束)。

调试示例 ​

命令行调试 ​
bash
busctl --user call bmc.kepler.ums /bmc/kepler/Managers/1/Ums/SP bmc.kepler.Managers.Ums.SP.Schema Update ss "<checksum>" "schema.zip"

2.12 BMA.UpgradePackage / DeletePackage(BMA 升级与删除) ​

功能说明 ​

  • UpgradePackage(ImageURI, SignatureURI, CrlURI):升级板载 BMA 安装包,支持本地/远程协议,要求 ImageURI 以 .tar.gz 结尾,SignatureURI 以 .cms 结尾,CrlURI 以 .crl 结尾。
  • DeletePackage():删除已上传的 BMA 安装包。
属性内容
接口名bmc.kepler.Managers.Ums.BMA.UpgradePackage / DeletePackage
废弃状态正常可用

参数说明 ​

参数名方向类型描述取值范围
ImageURI输入String升级包路径file:///https/sftp/nfs/cifs/scp,以 .tar.gz 结尾
SignatureURI输入String签名文件路径同上,以 .cms 结尾
CrlURI输入StringCRL 文件路径同上,以 .crl 结尾

返回值与异常 ​

| 返回值 | 含义 | 触发条件 | 处理建议 | | :--- | :--- | :--- | :--- | :--- | | task_id | 成功 | 升级任务创建成功 | 通过 Task 资源查询进度 | | 异常 upgrade_uri_illegal(-113) | URI 非法 | URI 格式或后缀不匹配 | 检查 URI | | 异常 cms_auth_error(-112) | 签名校验失败 | CMS 校验不通过 | 检查签名文件 |

应用场景 ​

通过 Redfish 或 OM 升级板载 iBMA 固件。

限制条件 ​

  • 升级过程中临时目录使用 kvm_user 属主。
  • 文件名最大长度 200。

调试示例 ​

命令行调试 ​
bash
busctl --user call bmc.kepler.ums /bmc/kepler/Managers/1/Ums/BMA bmc.kepler.Managers.Ums.BMA UpgradePackage sss "https://srv/ibma.tar.gz" "https://srv/ibma.cms" "https://srv/cms.crl"
busctl --user call bmc.kepler.ums /bmc/kepler/Managers/1/Ums/BMA bmc.kepler.Managers.Ums.BMA DeletePackage

2.13 IPMI 命令(CreateUms / CloseUms / GetUmsStatus / SP 相关) ​

功能说明 ​

提供与 Redfish 等价的 IPMI 命令通道,厂商命令 NetFn 0x30/0x92/0x93 系列,用于 SP 与 UMS 状态查询、控制、SP 信息读写。

属性内容
接口名UmsIpmiCmds(IPMI 命令组)
废弃状态正常可用

参数说明 ​

命令NetFn/Cmd子命令说明
CreateUms0x30/0x920x25, ParameterSelector=0x00创建 UMS,DeviceID 区分 SP/BMA
CloseUms0x30/0x920x25, ParameterSelector=0x03关闭 UMS
GetUmsStatus0x30/0x920x25, ParameterSelector=0x01查询 UMS 状态
GetSmartProvisioningInfo0x30/0x920x4C查询 SP 信息
SetSmartProvisioningInfo0x30/0x920x4D设置 SP 信息
GetSpDeviceInfoCollectEnableState0x30/0x930x5B/0x24查询 SP 设备信息采集开关
SetSpDeviceInfoCollectEnableState0x30/0x930x5A/0x24设置 SP 设备信息采集开关
GetSpBootTimes0x30/0x900x59/0x0E查询 SP 启动次数
SetSPResult0x30/0x930x47/0x00设置 SP 结果
SetSPTimeout0x30/0x930x47/0x01设置 SP 超时(300~86400s,默认 7200s)
SetSPFinished0x30/0x930x47/0x02设置 SP 完成标志
GetSpInfoOld / SetSpInfoOld0x30/0x930x36/0x35兼容旧万能命令(SetSpInfoOld 为敏感命令)

返回值与异常 ​

| 返回值 | 含义 | 触发条件 | 处理建议 | | :--- | :--- | :--- | :--- | :--- | | CompletionCode=0x00 | 成功 | 命令执行成功 | 无 | | CompletionCode=0xCB/0xC7 | 数据不可用/参数非法 | SP 对象不存在或参数非法 | 检查 SP 状态与参数 | | CompletionCode=0xD5 | 命令不可执行 | TPCM 限制或上下文不允许 | 检查 TPCM 与通道类型 |

应用场景 ​

OM/CLI 通过 IPMI 通道对 SP/UMS 进行带外管理与查询。

限制条件 ​

  • IPMI 命令需通过 HOST 通道类型下发(部分命令)。
  • SetSpInfoOld 为敏感命令,会被敏感信息脱敏处理。

调试示例 ​

命令行调试 ​
bash
ipmitool -I lanplus -H <bmc_ip> -U <user> -P <pwd> raw 0x30 0x92 0x07 0xDB 0x00 0x25 0x01 0x00 0x00
# 查询 UMS 状态(ParameterSelector=0x01, DeviceID=0x00 表示 BMA)

3. 组件扩展案例 ​

3.1 扩展能力概述 ​

ums 组件支持以下扩展能力:

  • SP 插件扩展:通过 SP.Plugin.Install 安装伙伴厂商提供的扩展插件,插件存放于 /data/sp/plugins/extend_plugins,内置插件存放于 /data/sp/plugins/builtin_plugins。
  • SP Schema 扩展:通过 SP.Schema.Update 动态更新 SP 服务的 Redfish Schema,扩展 SP 支持的资源模型;动态更新列表见 sp_schema.lua 中的 update_schema_info(HwSPRAID、HwSPOSInstallPara、HwSPDriveErase、HwSPDiagnose)。
  • JobFunction 扩展:通过 JobService/JobFunctions 下的 SPDiagnose/SPFWUpdate/SPOSInstall 三个 JobFunction 对接 Redfish 任务框架,可扩展新的 JobType。
  • 导入导出扩展:通过 mdb_config_manage.on_import/on_export 注册 SP 配置的导入导出回调,支持配置批量导入导出。
  • Dump 扩展:通过 intf_debug.on_dump 注册 SP 信息转储回调,支持一键日志收集时打包 /data/sp/spforbmc/spinfo。

3.2 扩展点说明 ​

  • SP.Plugin.Install:触发时机为 Redfish/OM 调用插件安装接口;作用是向 SP 注入伙伴扩展能力。
  • SP.Schema.Update:触发时机为 Redfish 调用 Schema 更新接口;作用是更新 SP Redfish 资源模型。
  • JobService/JobFunctions/SPDiagnose|SPFWUpdate|SPOSInstall:触发时机为 Redfish 创建对应任务;作用是异步执行 SP 诊断、固件升级、OS 安装。
  • mdb_config_manage.on_import/on_export:触发时机为 BMC 配置导入导出;作用是导入导出 SP 相关属性。
  • intf_debug.on_dump:触发时机为一键日志收集;作用是打包 SP 信息目录。

3.3 二次开发指导 ​

步骤一 ​

确认扩展类型:若扩展 SP 业务能力,选择 SP 插件方式;若扩展 Redfish 资源模型,选择 SP Schema 更新方式;若扩展异步任务,选择新增 JobFunction 方式。

步骤二 ​

按扩展类型准备物料:

  • SP 插件:制作 .tar.gz 插件包与对应 .cms 签名文件,确保单个插件组件数 ≤32、压缩文件数 ≤512。
  • SP Schema:制作 Schema 压缩包,单文件 ≤10M、文件数 ≤512,并提供 ChecksumValue。
  • JobFunction:在 mds/model.json 中新增 JobFunction 模型,并在 job/sp_job.lua 中扩展 JOB_TYPE/JOB_TO_UMS_FILE/JOB_TO_SCHEMA 等映射表。

示例代码 ​

以扩展 SP 插件为例,调用安装接口:

bash
busctl --user call bmc.kepler.ums /bmc/kepler/Managers/1/Ums/SP \
  bmc.kepler.Managers.Ums.SP.Plugin Install ss \
  "https://srv/myplugin.tar.gz" "https://srv/myplugin.cms"

验证方法 ​

  1. 调用 IsPluginInstalled 确认插件已安装。
  2. 调用 GetPluginInfo 查询插件详情,确认组件齐全。
  3. 通过 Redfish 调用插件提供的扩展接口,验证功能生效。

注意事项 ​

  • 插件包必须经过 CMS 签名校验,未通过校验的包会被拒绝。
  • 安装队列容量为 10,超出会返回 ResourceInUse。
  • U 盘利用率上限 95%,超出会拒绝写入。
  • Schema 更新前请确认 ChecksumValue 正确,避免解压失败。

4. 日志说明 ​

4.1 一键日志收集 ​

文件路径内容说明
/data/var/log/bmc/ums.logums 组件运行日志,由 dist/config.cfg 中 logger 配置输出
/data/sp/spforbmc/spinfo/SP 信息目录,通过 intf_debug.on_dump 注册,一键日志收集时会打包至 dump_info/AppDump/ums
/data/sp/spforbmc/operate/SP 业务文件目录(结果、部署任务、固件升级、诊断、RAID 等)

4.2 关键日志信息 ​

日志片段日志级别含义解读建议处理动作
UMS is not supported in this boardERROR当前板型不支持 SP,FlashDev 不可访问确认板型是否支持 SP,不需升级可忽略
sp upgrade failed: ums is busy now, OsAccessMode=%sERRORUMS 被主机 OS 占用,无法升级等待主机释放 UMS 后重试
sp upgrade failed: another task is runningERROR已有升级任务在运行等待当前升级任务完成
Upgrade SP failed: ImageURI illegalERRORImageURI 格式不匹配检查 URI 协议与后缀
Mount SP upgrade file failedERROR远程升级文件挂载失败检查远端服务器与协议配置
upgrade SP: file %s authenticate failedERROR升级包签名校验失败检查升级包与签名文件是否匹配
TPCM present is %s or basic trusted computing is enabledERRORTPCM 在位或可信计算使能,禁止挂载拔出 TPCM 或关闭可信计算
create BMA ums failed: %sERRORBMA UMS 挂载失败查看后续日志确认具体原因
Upgrade SP: sp update executeNOTICESP 升级开始执行无
sp upgrade: exit upgrade task, task_id = %sNOTICE升级任务退出无
poweroff or osreset, close ums bmaNOTICE主机下电或 OS 复位,自动卸载 BMA UMS无
ums backup sp device info: deviceinfo.json not existERROR升级前备份设备信息时文件不存在检查 SP 设备信息文件

5. 问题定界指南 ​

5.1 典型问题定界 ​

现象描述是否为本组件问题判断依据关键证据收集方法
SP 升级失败,提示 UMS 被占用是OsAccessMode 非 NoAccess,UMS 被主机占用查看 ums.log 中 OsAccessMode 相关日志,查询 bmc.kepler.Managers.Ums 的 OsAccessMode 属性
SP 升级失败,提示签名校验失败是CMS 校验未通过查看 ums.log 中 authenticate failed 日志,确认升级包与签名文件
创建 UMS 失败,提示 TPCM 限制是TPCM 在位或可信计算使能查看 ums.log 中 TPCM present 日志,查询 TPCM 在位状态与基础可信计算开关
SP 状态查询返回空串是电源状态读取失败查询 bmc.kepler.Systems.FruCtrl 的 PowerState 属性,查看 power_monitor 日志
远程升级文件挂载失败否(依赖 FileTransfer)远端协议挂载由 bmc.kepler.Managers.FileTransfer 完成查看 FileTransfer 服务日志,确认远端服务器与凭据
SP 心跳未建立导致状态为 SPIsOperable否(依赖 Sms)心跳由 bmc.kepler.Systems.Sms 上报查询 Sms/SmsStatus 对象状态,确认 SP 侧服务是否启动

5.2 错误码速查表 ​

错误码含义可能原因排查建议
-1未知下载错误下载流程异常查看 ums.log 中下载相关 ERROR 日志
-110UMS 被占用OsAccessMode 非 NoAccess等待主机释放 UMS 后重试
-111共享文件夹不可用远程挂载目录无法访问检查远端服务器与协议配置
-112CMS 签名校验失败URI 或 SP 文件不正确检查升级包与签名文件是否匹配
-113URI 格式非法ImageURI 协议或后缀不匹配检查 URI 协议与文件后缀
-115SP 忙SP 正在执行其他任务等待 SP 空闲后重试
-118UMS 挂载不可用挂载流程异常查看 ums.log 中挂载相关日志
-120需要 ARM 架构 SP 镜像平台与镜像架构不匹配使用 aarch64 架构的 SP 镜像
IPMI 0xCB数据不可用SP 对象不存在查询 SP 资源是否存在
IPMI 0xD5命令不可执行TPCM 限制或通道类型不允许检查 TPCM 状态与 IPMI 通道

5.3 调试方法 ​

开启调试日志 ​

在 dist/config.cfg 中调整 logger 级别(默认由 mc.logging 控制),或将日志级别设置为 debug 后重启 ums 服务:

bash
systemctl --user restart bmc.kepler.ums

复现问题方法 ​

  1. 前置条件设置:BMC 与主机连接正常,SP/BMA 分区可访问,确认 TPCM 不在位。
  2. 操作步骤:通过 Redfish 或 IPMI 触发对应操作(如 UpdateSP、CreateUms)。
  3. 预期现象:操作成功或按错误码表返回明确失败原因;查看 /data/var/log/bmc/ums.log 确认详细流程。

6. 常见问题解答 ​

Q1:SP 升级失败提示 UMS 被占用怎么办? ​

  • 问题描述:调用 UpdateSP 返回 UMSIsExclusivelyUsed。
  • 一句话答案:等待主机 OS 释放 U 盘后重试。
  • 根因说明:SP 升级需要独占访问 SP Flash 分区,当 OsAccessMode 非 NoAccess(主机正在访问 U 盘)时升级会被拒绝。
  • 解决方案:通过 CloseUms 关闭虚拟 U 盘或等待主机侧操作完成,确认 OsAccessMode 回到 NoAccess 后重新触发升级。
  • 规避方案:在主机下电状态下进行 SP 升级。
  • 适用版本:iBMC500 5.15.0 及以上。
  • 相关文档链接:见本文档 2.6 节 UpdateSP。

Q2:Auto 模式升级 SP 为什么会被转换为 Recover 模式? ​

  • 问题描述:以 UpdateMode=Auto 触发升级,实际执行的是 Recover 模式。
  • 一句话答案:Auto 模式会在分区异常或版本不兼容时自动降级为 Recover 以保证升级完整性。
  • 根因说明:check_update_mode 在以下情况会降级为 Recover:MajorVersion 变更、分区挂载失败、缺少 full.ini、缺少 version.json 或 version.json 校验和不匹配。
  • 解决方案:属于预期行为,无需处理;若频繁降级,检查 SP 分区与版本文件是否完整。
  • 规避方案:直接使用 Recover 模式升级。
  • 适用版本:iBMC500 5.15.0 及以上(1.130.3 修复 Auto 模式异常问题)。
  • 相关文档链接:见本文档 2.6 节 UpdateSP。

Q3:创建 UMS 失败提示 TPCM 限制怎么办? ​

  • 问题描述:调用 CreateUms 返回 IPMICommandCannotExecute,日志提示 TPCM 在位或可信计算使能。
  • 一句话答案:拔出 TPCM 或关闭基础可信计算能力后重试。
  • 根因说明:当 TPCM 在位或基础可信计算使能时,禁止 U 盘挂载卸载,防止可信链被破坏。
  • 解决方案:拔出 TPCM 模块或关闭基础可信计算开关,再调用 CreateUms。
  • 规避方案:无。
  • 适用版本:iBMC500 5.15.0 及以上(1.120.3 引入该限制)。
  • 相关文档链接:见本文档 2.1 节 CreateUms。

Q4:SP 插件安装失败提示签名校验失败怎么办? ​

  • 问题描述:调用 SP.Plugin.Install 返回 cms_auth_error(-112)。
  • 一句话答案:使用与插件包匹配的签名文件并确认根证书已导入。
  • 根因说明:插件包必须经过 CMS 签名校验,签名文件与升级包不匹配或根证书缺失会导致校验失败。
  • 解决方案:重新生成与插件包匹配的 .cms 签名文件,确认 /opt/bmc/trust/partner/rootca.der 或国密证书已就位。
  • 规避方案:使用经过官方签名的插件包。
  • 适用版本:iBMC500 5.15.0 及以上(1.120.1 支持伙伴自签名固件包升级)。
  • 相关文档链接:见本文档 2.10 节 SP 插件管理。

Q5:SP 状态查询返回空串或状态异常怎么办? ​

  • 问题描述:GetSPStatus 返回空串或与预期不符。
  • 一句话答案:先确认电源状态与 SP 版本信息。
  • 根因说明:状态判定按优先级依次检查 FlashDev、APPVersion、ums.Enable、电源状态、BiosSupport、心跳;电源状态读取失败会返回空串。
  • 解决方案:查询 bmc.kepler.Systems.FruCtrl 的 PowerState 属性确认电源状态;查询 bmc.kepler.Managers.Ums.SP.Version 确认 APPVersion 是否有效。
  • 规避方案:无。
  • 适用版本:iBMC500 5.15.0 及以上。
  • 相关文档链接:见本文档 2.8 节 GetSPStatus。

附录 ​

附录A 参考资料 ​

  • openUBMC 官方文档:组件开发指南、MDB 接口规范
  • IPMI 规范:NetFn 0x30/0x92/0x93 厂商命令

附录B 修订记录 ​

版本日期修订人修订内容
v1.02026-10-19openUBMC按组件文档说明模板重写 README,覆盖组件概述、API、扩展、日志、定界、FAQ