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 关键术语表(可选)
| 术语 | 解释 |
|---|---|
| UMS | USB Mass Storage,USB 大容量存储协议,本组件将 Flash 分区虚拟为 U 盘供主机访问 |
| SP | SmartProvisioning,主机侧智能部署服务,由本组件负责升级及业务文件下发 |
| BMA | 板载 iBMA(Baseboard Management Agent),本组件负责其分区挂载与固件升级 |
| PathId | U盘文件读写的目录枚举值,1~13 分别对应不同的 SP 业务目录 |
| CMS | Cryptographic Message Syntax,用于升级包签名校验 |
| TPCM | Trusted 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 | 输入 | U8 | U 盘类型 | 0:本地 U 盘;1:远程 U 盘 |
| Type | 输入 | U8 | 挂载类型 | 0:临时挂载;1:正式挂载;>1 视为非法 |
返回值与异常
| 返回值 | 含义 | 触发条件 | 处理建议 |
|---|---|---|---|
| 0 | 成功 | U 盘挂载任务创建成功 | 无 |
| -110 | UMS 被占用 | OsAccessMode 非 NoAccess,U 盘被主机 OS 占用 | 等待主机释放后重试 |
| 异常 PropertyModificationNotSupported | 参数不支持 | Type>1 或对象 ID 不含 BMA | 检查参数与对象路径 |
| 异常 IPMICommandCannotExecute | TPCM 限制 | TPCM 在位或基础可信计算使能 | 关闭可信计算或拔出 TPCM 后重试 |
应用场景
主机需要在 OS 侧访问 SP/BMA Flash 内的部署文件、诊断结果、升级包时,通过本接口将 Flash 分区虚拟为 U 盘。
限制条件
- 调用前需确认 TPCM 不在位且基础可信计算未使能。
- 一次仅允许一个挂载任务,重复调用需等待前序任务完成。
- 电源关闭或 OS 复位时会自动卸载 U 盘。
调试示例
命令行调试
# 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 02.2 CloseUms(关闭虚拟 U 盘)
功能说明
卸载并断开已挂载到主机侧的 SP/BMA 虚拟 U 盘,释放 USB 通道与挂载点。
| 属性 | 内容 |
|---|---|
| 接口名 | bmc.kepler.Managers.Ums.CloseUms |
| 废弃状态 | 正常可用 |
参数说明
| 参数名 | 方向 | 类型 | 描述 | 取值范围 |
|---|---|---|---|---|
| - | - | - | 本接口无输入参数 | - |
返回值与异常
| 返回值 | 含义 | 触发条件 | 处理建议 | | :--- | :--- | :--- | :--- | :--- | | 0 | 成功 | 卸载任务创建成功 | 无 | | 异常 PropertyModificationNotSupported | 不支持 | 对象 ID 不含 BMA 或已有任务运行中 | 等待任务完成或检查对象 |
应用场景
升级任务完成后、主机下电前,或业务侧主动需要回收 U 盘时调用。
限制条件
- 一次仅允许一个卸载任务,重复调用需等待前序任务完成。
- 同样受 TPCM/基础可信计算限制。
调试示例
命令行调试
busctl --user call bmc.kepler.ums /bmc/kepler/Managers/1/Ums/BMA bmc.kepler.Managers.Ums CloseUms2.3 ReadFile(读 U 盘文件)
功能说明
按 PathId 读取 U 盘内指定文件的内容,返回文件原始数据。读操作会获取 UMS 传输锁并确认 U 盘未被主机占用。
| 属性 | 内容 |
|---|---|
| 接口名 | bmc.kepler.Managers.Ums.ReadFile |
| 废弃状态 | 正常可用 |
参数说明
| 参数名 | 方向 | 类型 | 描述 | 取值范围 |
|---|---|---|---|---|
| PathId | 输入 | U8 | 文件路径 id | 1~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配置范围内。
调试示例
命令行调试
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 | 文件路径 id | 1~13 |
| FileName | 输入 | String | 文件名 | 不含 / 与 .. |
| Content | 输入 | String | 写入内容 | 单文件最大 2MB |
返回值与异常
| 返回值 | 含义 | 触发条件 | 处理建议 | | :--- | :--- | :--- | :--- | :--- | | 0 | 成功 | 写入成功 | 无 | | 异常 UMSIsExclusivelyUsed | UMS 被占用 | OsAccessMode 非 NoAccess | 等待主机释放 |
应用场景
OM 向 SP 下发部署任务、诊断任务、固件升级包元数据时调用。
限制条件
- 同 ReadFile 的路径与大小限制。
- 每个目录最大文件数 50(
UMS_MAX_FILE_CNT),U 盘利用率上限 95%。
调试示例
命令行调试
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 | 文件路径 id | 1~13 |
| FileName | 输入 | String | 文件名(仅 CheckFileExist) | 不含 / 与 .. |
返回值与异常
| 返回值 | 含义 | 触发条件 | 处理建议 | | :--- | :--- | :--- | :--- | :--- | | 文件列表 / 布尔 / 0 | 成功 | 操作成功 | 无 | | 异常 UMSIsExclusivelyUsed | UMS 被占用 | OsAccessMode 非 NoAccess | 等待主机释放 |
应用场景
OM 在下发任务前查询目录、确认文件是否就绪,或任务完成后清理目录。
限制条件
- 同 ReadFile 的路径与挂载状态限制。
调试示例
命令行调试
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 42.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 服务挂载成功。
调试示例
命令行调试
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。
调试示例
命令行调试
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 |
| 废弃状态 | 正常可用 |
参数说明
| 参数名 | 方向 | 类型 | 描述 | 取值范围 |
|---|---|---|---|---|
| - | - | - | 无输入参数 | - |
| 返回 | 输出 | String | SP 状态字符串 | 见下表 |
返回值取值:
| 状态 | 含义 |
|---|---|
| SPPartitionTableNotExist | SP FlashDev 不可访问,分区表不存在 |
| SPNeedsUpdate | APPVersion 无效,需要升级 SP |
| iBMCNeedsUpdate | ums.Enable 为 false,iBMC 需要升级 |
| OSIsPoweredOff | 主机电源为 OFF |
| BIOSNeedsUpdate | ums.BiosSupport 为 false,BIOS 需要升级 |
| SPIsOperable | SP 与 BMC 心跳未建立,SP 可操作 |
| SPIsWorking | SP 与 BMC 心跳已建立,SP 工作中 |
返回值与异常
| 返回值 | 含义 | 触发条件 | 处理建议 | | :--- | :--- | :--- | :--- | :--- | | 状态字符串 | 成功 | 正常执行 | 无 | | 空串 | 电源状态未知 | 电源状态读取失败 | 检查 FruCtrl 服务 |
应用场景
OM/Redfish 在执行 SP 业务前查询 SP 是否就绪、是否需要升级。
限制条件
无特殊限制。
调试示例
命令行调试
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 GetSPStatus2.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 |
| 废弃状态 | 正常可用 |
参数说明
| 参数名 | 方向 | 类型 | 描述 | 取值范围 |
|---|---|---|---|---|
| - | - | - | 无输入参数 | - |
| 返回 | 输出 | String | JSON 字符串 | 见功能说明 |
返回值与异常
| 返回值 | 含义 | 触发条件 | 处理建议 | | :--- | :--- | :--- | :--- | :--- | | JSON 字符串 | 成功 | 读取成功 | 无 | | 异常 InternalError | 内部错误 | UMS 挂载失败或文件解析失败 | 检查 SP 状态与文件 | | 异常 ResourceInUse | 资源占用 | 传输锁获取失败 | 等待释放后重试 |
应用场景
Redfish Sms/{n}/Managers/1/SPService/SPResult/1 接口透传 SP 任务结果;OM 通过 GetSPServiceSignature 确认签名格式。
限制条件
- 同 ReadFile 的挂载与锁限制。
调试示例
命令行调试
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 GetOSInstallPara2.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%。
调试示例
命令行调试
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 | 输入 | String | Schema 文件名 | 非空字符串 |
返回值与异常
| 返回值 | 含义 | 触发条件 | 处理建议 | | :--- | :--- | :--- | :--- | :--- | | 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(路径数量上限,当前代码未引用,保留作为预留约束)。
调试示例
命令行调试
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 | 输入 | String | CRL 文件路径 | 同上,以 .crl 结尾 |
返回值与异常
| 返回值 | 含义 | 触发条件 | 处理建议 | | :--- | :--- | :--- | :--- | :--- | | task_id | 成功 | 升级任务创建成功 | 通过 Task 资源查询进度 | | 异常 upgrade_uri_illegal(-113) | URI 非法 | URI 格式或后缀不匹配 | 检查 URI | | 异常 cms_auth_error(-112) | 签名校验失败 | CMS 校验不通过 | 检查签名文件 |
应用场景
通过 Redfish 或 OM 升级板载 iBMA 固件。
限制条件
- 升级过程中临时目录使用
kvm_user属主。 - 文件名最大长度 200。
调试示例
命令行调试
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 DeletePackage2.13 IPMI 命令(CreateUms / CloseUms / GetUmsStatus / SP 相关)
功能说明
提供与 Redfish 等价的 IPMI 命令通道,厂商命令 NetFn 0x30/0x92/0x93 系列,用于 SP 与 UMS 状态查询、控制、SP 信息读写。
| 属性 | 内容 |
|---|---|
| 接口名 | UmsIpmiCmds(IPMI 命令组) |
| 废弃状态 | 正常可用 |
参数说明
| 命令 | NetFn/Cmd | 子命令 | 说明 |
|---|---|---|---|
| CreateUms | 0x30/0x92 | 0x25, ParameterSelector=0x00 | 创建 UMS,DeviceID 区分 SP/BMA |
| CloseUms | 0x30/0x92 | 0x25, ParameterSelector=0x03 | 关闭 UMS |
| GetUmsStatus | 0x30/0x92 | 0x25, ParameterSelector=0x01 | 查询 UMS 状态 |
| GetSmartProvisioningInfo | 0x30/0x92 | 0x4C | 查询 SP 信息 |
| SetSmartProvisioningInfo | 0x30/0x92 | 0x4D | 设置 SP 信息 |
| GetSpDeviceInfoCollectEnableState | 0x30/0x93 | 0x5B/0x24 | 查询 SP 设备信息采集开关 |
| SetSpDeviceInfoCollectEnableState | 0x30/0x93 | 0x5A/0x24 | 设置 SP 设备信息采集开关 |
| GetSpBootTimes | 0x30/0x90 | 0x59/0x0E | 查询 SP 启动次数 |
| SetSPResult | 0x30/0x93 | 0x47/0x00 | 设置 SP 结果 |
| SetSPTimeout | 0x30/0x93 | 0x47/0x01 | 设置 SP 超时(300~86400s,默认 7200s) |
| SetSPFinished | 0x30/0x93 | 0x47/0x02 | 设置 SP 完成标志 |
| GetSpInfoOld / SetSpInfoOld | 0x30/0x93 | 0x36/0x35 | 兼容旧万能命令(SetSpInfoOld 为敏感命令) |
返回值与异常
| 返回值 | 含义 | 触发条件 | 处理建议 | | :--- | :--- | :--- | :--- | :--- | | CompletionCode=0x00 | 成功 | 命令执行成功 | 无 | | CompletionCode=0xCB/0xC7 | 数据不可用/参数非法 | SP 对象不存在或参数非法 | 检查 SP 状态与参数 | | CompletionCode=0xD5 | 命令不可执行 | TPCM 限制或上下文不允许 | 检查 TPCM 与通道类型 |
应用场景
OM/CLI 通过 IPMI 通道对 SP/UMS 进行带外管理与查询。
限制条件
- IPMI 命令需通过 HOST 通道类型下发(部分命令)。
SetSpInfoOld为敏感命令,会被敏感信息脱敏处理。
调试示例
命令行调试
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 插件为例,调用安装接口:
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"验证方法
- 调用
IsPluginInstalled确认插件已安装。 - 调用
GetPluginInfo查询插件详情,确认组件齐全。 - 通过 Redfish 调用插件提供的扩展接口,验证功能生效。
注意事项
- 插件包必须经过 CMS 签名校验,未通过校验的包会被拒绝。
- 安装队列容量为 10,超出会返回 ResourceInUse。
- U 盘利用率上限 95%,超出会拒绝写入。
- Schema 更新前请确认 ChecksumValue 正确,避免解压失败。
4. 日志说明
4.1 一键日志收集
| 文件路径 | 内容说明 |
|---|---|
| /data/var/log/bmc/ums.log | ums 组件运行日志,由 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 board | ERROR | 当前板型不支持 SP,FlashDev 不可访问 | 确认板型是否支持 SP,不需升级可忽略 |
sp upgrade failed: ums is busy now, OsAccessMode=%s | ERROR | UMS 被主机 OS 占用,无法升级 | 等待主机释放 UMS 后重试 |
sp upgrade failed: another task is running | ERROR | 已有升级任务在运行 | 等待当前升级任务完成 |
Upgrade SP failed: ImageURI illegal | ERROR | ImageURI 格式不匹配 | 检查 URI 协议与后缀 |
Mount SP upgrade file failed | ERROR | 远程升级文件挂载失败 | 检查远端服务器与协议配置 |
upgrade SP: file %s authenticate failed | ERROR | 升级包签名校验失败 | 检查升级包与签名文件是否匹配 |
TPCM present is %s or basic trusted computing is enabled | ERROR | TPCM 在位或可信计算使能,禁止挂载 | 拔出 TPCM 或关闭可信计算 |
create BMA ums failed: %s | ERROR | BMA UMS 挂载失败 | 查看后续日志确认具体原因 |
Upgrade SP: sp update execute | NOTICE | SP 升级开始执行 | 无 |
sp upgrade: exit upgrade task, task_id = %s | NOTICE | 升级任务退出 | 无 |
poweroff or osreset, close ums bma | NOTICE | 主机下电或 OS 复位,自动卸载 BMA UMS | 无 |
ums backup sp device info: deviceinfo.json not exist | ERROR | 升级前备份设备信息时文件不存在 | 检查 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 日志 |
| -110 | UMS 被占用 | OsAccessMode 非 NoAccess | 等待主机释放 UMS 后重试 |
| -111 | 共享文件夹不可用 | 远程挂载目录无法访问 | 检查远端服务器与协议配置 |
| -112 | CMS 签名校验失败 | URI 或 SP 文件不正确 | 检查升级包与签名文件是否匹配 |
| -113 | URI 格式非法 | ImageURI 协议或后缀不匹配 | 检查 URI 协议与文件后缀 |
| -115 | SP 忙 | SP 正在执行其他任务 | 等待 SP 空闲后重试 |
| -118 | UMS 挂载不可用 | 挂载流程异常 | 查看 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 服务:
systemctl --user restart bmc.kepler.ums复现问题方法
- 前置条件设置:BMC 与主机连接正常,SP/BMA 分区可访问,确认 TPCM 不在位。
- 操作步骤:通过 Redfish 或 IPMI 触发对应操作(如
UpdateSP、CreateUms)。 - 预期现象:操作成功或按错误码表返回明确失败原因;查看
/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.0 | 2026-10-19 | openUBMC | 按组件文档说明模板重写 README,覆盖组件概述、API、扩展、日志、定界、FAQ |