rmcpd

版本信息

项目	内容
组件版本	1.140.14
首发版本	1.140.11
文档作者	openUBMC 社区
最后更新	2026-09-13

1. 组件概述

1.1 组件简介

rmcpd 是 openUBMC 平台的带外 IPMI 通信管理组件，负责 RMCP/RMCP+（IPMI over LAN）协议收发与会话管理，以及 SOL（Serial Over LAN，串口重定向）会话管理。

1.2 解决什么问题

rmcpd 提供通过带外管理通道的底层协议能力，使管理员能够通过局域网以 IPMI 协议远程访问服务器串口，以实现调试、维护等操作。包含：

• RMCP（IPMI v1.5）：基于 UDP 的远程管理控制协议。
• RMCP+（IPMI v2.0）：增加会话认证（RAKP）、完整性校验与加密（AES-CBC-128）。
• SOL：IPMI SOL 与本地 CLI SOL（TCP 8210）两种模式的串口控制台会话管理。

1.3 核心功能

• 核心功能一：带外IPMI通信管理

  支持 RMCP 和 RMCP+ 协议，处理 IPMI 消息传递，实现 IPMI 命令的解析与执行，支持加密算法套件的选择与鉴权过程。

• 核心功能二：SOL（Serial Over Lan）会话管理

  提供串口重定向功能，允许用户通过网络访问 BMC 管理的串口；支持通过 CLI 或资源协作接口启动和管理 SOL 会话；实现 SOL 流程，包括串口数据的读写和会话的状态管理。

1.4 关键术语表

术语	解释
RMCP	IPMI v1.5 使用的远程管理控制协议。
RMCP+	IPMI v2.0 协议，提供认证、完整性校验和加密。
SOL	Serial Over LAN，串口重定向。
Cipher Suite	RMCP+ 使用的认证、完整性和加密算法组合。
payload	IPMI 会话承载的功能数据，例如 SOL 和用户配置。

1.5 外部交互边界图

rmcpd 通过资源协作接口与其他组件协作，对外发布 4 个接口，同时依赖其他组件的资源。

组件仓使用协议类 protocol，该类可以添加子协议，不同的协议通过 pop 方法往子协议抛数据，由 IPMI 协议处理，之后再通过 push 方法向下传递，向客户端响应数据。

flowchart LR
	UDP["UDP"]
	RMCP["RMCP"]
	RMCP_PLUS["RMCP+"]
	IPMI["IPMI"]

	UDP --> |POP| RMCP
	RMCP --> |PUSH| UDP

	RMCP --> |POP| RMCP_PLUS
	RMCP_PLUS --> |PUSH| RMCP

	RMCP_PLUS --> |POP| IPMI
	IPMI --> |PUSH| RMCP_PLUS

---

2. API 使用说明与示例

对外发布的 API 为资源协作接口，服务名 bmc.kepler.rmcpd，ManagerId 默认为 1，均可通过 busctl/mdbctl 调试。

# 查看资源协作接口
busctl --user tree bmc.kepler.rmcpd

2.1 bmc.kepler.Managers.Rmcp.SessionService

功能说明

配置 RMCP 最大并发会话数。

路径：/bmc/kepler/Managers/${ManagerId}/Rmcp

参数说明

属性	类型	读写	默认值	范围	说明
MaxConcurrentSessions	y	可读写	15	5~15	RMCP 最大并发会话数

返回值与异常

设置越界时抛 PropertyValueOutOfRange。

应用场景

用于限制同时建立的 RMCP/RMCP+ 会话数量。

限制条件

取值必须在 5～15 范围内，写入后立即影响新会话。

调试示例

busctl --user get-property bmc.kepler.rmcpd /bmc/kepler/Managers/1/Rmcp \
    bmc.kepler.Managers.Rmcp.SessionService MaxConcurrentSessions   # 响应 y 5

busctl --user set-property bmc.kepler.rmcpd /bmc/kepler/Managers/1/Rmcp \
    bmc.kepler.Managers.Rmcp.SessionService MaxConcurrentSessions y 10

2.2 bmc.kepler.Managers.SOL

功能说明

SOL 全局配置（使能/模式/串口/超时/payload 端口）与会话初始化。

路径：/bmc/kepler/Managers/${ManagerId}/SOL

参数说明

属性	类型	读写	说明
Enabled	b	只读	SOL 是否使能
Mode	y	只读	会话模式（0=共享，1=独占）
SerialDirect	y	只读	串口直连标识
Timeout	q	只读	会话超时（分钟）
PayloadPort	q	可读写	SOL payload 端口

方法	入参	出参	说明
InitSession	a{ss}y（上下文 + 模式）	y	初始化 SOL 会话
SetTimeout	a{ss}q（上下文 + 超时分钟）	y	设置会话超时时间

入参 a{ss} 为上下文，含 Interface、UserName、ClientAddr 三个键值对。

返回值与异常

InitSession 返回码：0 成功；1 模式越界；2 IPMI_SOL 已激活，被 IPMI_SOL 占用；3 独占模式；4 模式不匹配；5 会话数满；6 SOL 被禁用；7 共享模式系统 ID 冲突。

SetTimeout 返回码：0 成功；1 超时时间越界（0~480 分钟）。

应用场景

用于配置 SOL 全局使能、模式、串口、超时和 payload 端口。

限制条件

部分属性只读；写入需要对应模型权限，并使当前配置满足 SOL 状态约束。

调试示例

busctl --user get-property bmc.kepler.rmcpd /bmc/kepler/Managers/1/SOL \
    bmc.kepler.Managers.SOL Enabled

busctl --user call bmc.kepler.rmcpd /bmc/kepler/Managers/1/SOL \
    bmc.kepler.Managers.SOL InitSession a{ss}y \
    3 Interface Busctl UserName Administrator ClientAddr 127.0.0.1 0   # 返回 y 0

2.3 bmc.kepler.Managers.SOL.Session

功能说明

单个 SOL 会话状态信息与会话去激活。

路径：/bmc/kepler/Managers/${ManagerId}/SOL/Session/${Id}

参数说明

属性	类型	读写	描述
Activated	b	只读	会话的激活状态
Type	s	只读	SOL会话类型（"CLI" 或 "IPMI"）
ClientAddress	s	只读	客户端会话地址，IP:端口
ActivatedTime	s	只读	登录时间
UserName	s	只读	登录用户名

方法	入参	出参	说明
Deactivate	a{ss}	y	去激活会话

返回值与异常

Deactivate 返回码：0 成功；1 会话 ID 越界（非 1~2）；2 被 IPMI_SOL 占用；3 会话已关闭。

应用场景

用于初始化、监控和维护单个 SOL 会话。

限制条件

会话模式必须合法，且不能超过最大会话数；SOL 被禁用或串口被占用时初始化失败。

调试示例

busctl --user get-property bmc.kepler.rmcpd /bmc/kepler/Managers/1/SOL/Session/1 \
    bmc.kepler.Managers.SOL.Session Activated

busctl --user call bmc.kepler.rmcpd /bmc/kepler/Managers/1/SOL/Session/1 \
    bmc.kepler.Managers.SOL.Session Deactivate a{ss} \
    3 Interface Busctl UserName Administrator ClientAddr 127.0.0.1

2.4 bmc.kepler.Managers.RMCPCipherSuites

功能说明

RMCP+ 算法套件使能配置及套件算法查询。

路径：/bmc/kepler/Managers/${ManagerId}/RMCPCipherSuites/${Id}

参数说明

属性	类型	读写	说明
SuitId	y	只读	套件 ID，取值 {1,2,3,17}
Enabled	b	可读写	是否使能
AuthenticationAlgorithm	s	只读	None/RAKP-HMAC-SHA1/RAKP-HMAC-SHA256
IntegrityAlgorithm	s	只读	None/HMAC-SHA1-96/HMAC-SHA256-128
ConfidentialityAlgorithm	s	只读	None/AES-CBC-128

返回值与异常

尝试禁用所有套件时抛 AllCipherSuitesDisabled。

应用场景

用于查询或调整 RMCP+ Cipher Suite 的使能状态。

限制条件

不能禁用全部套件；启用或禁用不安全套件会触发安全告警。

调试示例

busctl --user get-property bmc.kepler.rmcpd /bmc/kepler/Managers/1/RMCPCipherSuites/17 \
    bmc.kepler.Managers.RMCPCipherSuites Enabled

busctl --user set-property bmc.kepler.rmcpd /bmc/kepler/Managers/1/RMCPCipherSuites/1 \
    bmc.kepler.Managers.RMCPCipherSuites Enabled b false

2.5 IPMI 命令

功能说明

rmcpd 还通过 RMCP/RMCP+ 会话提供 IPMI 命令处理（定义见 mds/ipmi.json），主要类别：

• 会话类：GetSessionChallenge、ActivateSession、SetSessionPrivilegeLevel、CloseSession、GetSessionInfo。
• 通道类：Set/GetChannelAccess、GetChannelInfo、SetChannelSecurityKeys、GetChannelAuthCapabilities。
• 算法套件类：GetChannelCipherSuites、Set/GetCipherSupport、Set/GetCiphers、Set/GetCipherSuitePriv。
• SOL 负载类：ActivatePayload、DeactivatePayload、Set/GetSOLConfigurationParameters、GetPayloadActivationStatus、GetPayloadInstanceInfo、SuspendResumePayloadEncryption、GetSOLDestNumber/Name。

参数说明

命令、请求字段和权限来自 mds/ipmi.json，并按 IPMI 标准 NetFn/Cmd 编码传递。

返回值与异常

成功返回标准 IPMI 完成码 0x00；参数、权限和状态错误返回 5.2 节列出的完成码。

应用场景

用于远端客户端建立 IPMI 会话、管理通道和 Cipher Suite，以及控制 SOL/user payload。

限制条件

必须先建立合法 RMCP/RMCP+ 会话；系统 LockDown 时配置写命令被禁止。

调试示例

使用 ipmitool 或产品 IPMI 工具在隔离环境验证，禁止在生产设备执行未确认的配置命令。

会话类与 payload 激活/去激活命令的协议处理已下沉到 C 库（ipmi_rmcp_lib），Lua 侧仅保留权限校验与定制入口。

---

3. 组件扩展案例

3.1 扩展能力概述

项目采用了模块化的实现，支持插件机制、配置文件定制和代码级二次开发。

3.2 扩展点说明

• IPMI 命令扩展：src/lualib/commands/ 下新增命令模块
• 定制化配置：customize_config.lua（BMCSet_RMCPCipherSuites_<id>、BMCSet_RmcpMaxConcurrentSessions）
• 配置导入/导出回调：mc.mdb.micro_component.config_manage 的 on_import/on_export
• C 库扩展：src/luaclib/ipmi_rmcp_lib（c_ipmi_lib 模块）

3.3 二次开发指导

3.3.1 新增 IPMI 命令

在 src/lualib/commands/ 新增一个 my_cmd 模块，并在 commands/init.lua 添加：

-- src/lualib/commands/my_cmd.lua
local cmds = {}
function cmds.MyCustomCmd(req, ctx)
    -- 业务逻辑
    return ipmi_msg.MyCustomCmd.rsp.new()
end
return cmds

-- commands/init.lua
local cmds_modules = {'ipmi_channel_info', 'lan_config', 'self_config', 'sol', 'user', 'my_cmd'}

验证方法：在 mds/ipmi.json 补充命令定义 → 重新生成代码（bingo gen）→ 通过 ipmitool 下发验证。

注意事项：函数名必须与 ipmi.json 中 cmds 键名一致；已下沉到 C 库的命令在 Lua 侧仅做权限校验。

3.3.2 配置导入/导出回调

mdb_config_manage.on_import(function(ctx, config_data, import_type)
    cfg_mgmt.import(ctx, self.suite_objs, config_data, import_type)
end)
mdb_config_manage.on_export(function(ctx, import_type)
    return cfg_mgmt.export(ctx, self.suite_objs, import_type)
end)

---

4. 日志说明

• 组件使用 openUBMC 日志框架 mc.logging，模块名 MODULE_NAME = "rmcpd"，日志路径 /var/log/app.log，级别含 debug/info/notice/warn/error 及审计日志 log:operation。

4.1 一键日志收集

通过 dump.lua 注册 mc.mdb.micro_component.debug.on_dump 回调。执行一键收集时生成 rmcpd_dumpinfo 文件，内容为以下对象属性快照：

收集项	属性
SOL	Id、AuthenWay、EncryWay、PrivilegeLevel、SendThreshold、SendInterval、RetryCount、RetryInterval、SetProgress、IPMISOLEnabled
UserPayload	Id、StandardPayloadSupport、StandardPayloadEnable
ChannelConfig	Id、PrivilegeLimit、AccessSet、PEFEnable、AuthMethod、UserAuthEnable、AccessMode、PrivilegeSet、StandardPayloadSupport、SessionPayloadSupport、OEMPayloadSupport、KGValue

4.2 关键日志信息

级别	典型日志	含义
error	register protocol(RMCP) failed	RMCP 协议注册失败
error	restart rmcp socket failed	RMCP socket 重建失败
notice	restart rmcp socket success	RMCP socket 重建成功
error	Out of sequence SOL packet - packet is dropped	SOL 报文乱序丢弃
operation	Connect SOL successfully / Disconnect SOL successfully	SOL 会话建立/断开
operation	Enable/Disable RMCP Cipher Suite(ID %d) successfully	套件使能/禁用

---

5. 问题定界指南

5.1 典型问题定界

现象	是否属于 rmcpd	判断要点
ipmitool 无法建立 RMCP/RMCP+ 会话	可能	端口 623/664 监听、register protocol 日志、账户锁定
SOL 会话无法建立	可能	InitSession 返回码、串口资源就绪
配置类命令返回错误	可能	系统是否 LockDown
IPMI 返回 0xCC/0xC7/0xC9 等	是	见 5.2 错误码表
串口无输出	可能	串口设备权限、UartPort 资源

5.2 最小化复现与证据收集

1. 记录目标协议、端口、账号权限、系统 LockDown 状态和 IPMI 完成码。
2. 抓取 UDP 623/664 会话握手，保留 RMCP/RMCP+ 日志。
3. SOL 问题记录 InitSession 返回码、串口资源和 payload 占用状态。
4. 执行一键日志收集并检查 rmcpd_dumpinfo。

5.3 错误码速查表

IPMI 完成码（定义见 mds/errors.json）：

完成码	含义
0x00	成功
0x80	参数不支持
0x82	只读参数
0xC1	非法命令
0xC7	请求数据长度非法
0xC9	参数越界
0xCC	字段非法

SOL 方法返回码：见 2.2 与 2.3。

5.4 调试/复现方法

busctl --user tree bmc.kepler.rmcpd   # 查看组件资源协作接口
busctl --user introspect bmc.kepler.rmcpd /bmc/kepler/Managers/1/SOL/Session/1

• 执行一键日志收集，检查 rmcpd_dumpinfo 快照。
• 客户端抓取 UDP 623/664 报文，确认 RMCP/RMCP+ 握手。

---

6. 常见问题解答

Q1：ipmitool 无法建立 RMCP/RMCP+ 会话？

• 问题描述：客户端无法建立 IPMI over LAN 会话。
• 一句话答案：检查 623/664 监听、协议注册和账号锁定状态。
• 根因说明：协议注册失败、端口未监听或账号被锁定都会阻止会话建立。
• 解决方案：查看 register protocol(RMCP) failed 日志，检查端口和账号状态，必要时抓包分析握手。
• 规避方案：变更网络或账号配置前保留原配置和会话验证结果。
• 适用版本：1.140.13。

Q2：SOL 会话建立失败，InitSession 返回非 0？

• 问题描述：SOL 会话初始化失败。
• 一句话答案：按返回码检查模式、占用、会话数和使能状态。
• 根因说明：返回码 1/2/5/6 分别对应模式越界、被 IPMI SOL 占用、会话数满和 SOL 禁用。
• 解决方案：断开冲突会话或清理空闲会话，确认 mode 参数与 Enabled 属性。
• 规避方案：建立会话前检查当前 SOL 会话和配置状态。
• 适用版本：1.140.13。

Q3：禁用算法套件报错或告警？

• 问题描述：修改 Cipher Suite 使能状态失败或触发安全告警。
• 一句话答案：不能禁用全部套件，不安全套件变化会产生告警。
• 根因说明：组件要求至少保留一个可用套件，并审计安全性变化。
• 解决方案：保留至少一个套件；安全加固时仅保留推荐套件。
• 规避方案：变更前记录套件状态，在维护窗口逐项调整并复核客户端兼容性。
• 适用版本：1.140.13。

Q4：配置类命令返回错误？

• 问题描述：SetChannelAccess 等配置命令失败。
• 一句话答案：检查系统 LockDown 状态、权限和参数范围。
• 根因说明：锁定状态下写命令被禁止，权限或参数不满足模型约束时也会失败。
• 解决方案：解除锁定后重试，并按 mds/ipmi.json 核对权限和参数。
• 规避方案：批量配置前先做只读查询，并在隔离环境验证命令。
• 适用版本：1.140.13。

Q5：串口无输出或 SOL 连接串口失败？

• 问题描述：SOL 会话建立后没有数据，或连接串口失败。
• 一句话答案：检查串口设备权限与 SerialManagement/UartPort 资源。
• 根因说明：设备节点权限、串口资源或初始化流程异常会阻止数据转发。
• 解决方案：确认 chmod/chown 已执行，检查 UartPort 对象，并检索 Init uart failed 日志。
• 规避方案：不要在生产环境直接修改设备节点权限，应在产品配置中固化。
• 适用版本：1.140.13。