maca ​

版本信息 ​

1. 组件概述 ​

1.1 组件简介 ​

maca（micro & agile component architecture）是 openUBMC 微组件运行框架中的核心管理组件。mds/service.json 将其声明为 application，description 为 framework main component，deployConfig 为 framework.service。它负责收集活动微组件、检查启动/健康/在线状态、维护 MDB 资源树索引，并代理 BMC 强制复位、平滑复位、组件热复位、复位锁、看门狗、日志系统自愈、配置备份和一键收集等系统级能力。

对外注册的 D-Bus 服务名为 bmc.kepler.maca。Release 主对象为：

/bmc/kepler/MacaService
/bmc/kepler/MdbService
/bmc/kepler/Managers/${ManagerId}/Package

Debug 构建还可能创建 /bmc/kepler/Debug/LogMock 与 /bmc/kepler/Debug/Performance。

源码同时保留独立 maca.service 单元（工作目录 /opt/bmc/apps/maca，ExecStart 为 Skynet + config.cfg）。目标产品究竟采用 framework 内嵌部署还是独立 systemd 单元，以对应 Manifest 和镜像为准。

组件不提供 IPMI 命令（MDS 中无 ipmi.json）。mds/service.json 的 required 为空。构建依赖 libmc4lua、persistence；测试依赖含 mdb_interface、hwproxy 等。

1.2 解决什么问题 ​

• 统一管理微组件生命周期：发现常驻组件，识别启动失败、健康异常和连续掉线，并按策略重启子系统或复位 BMC。
• 提供一致的系统复位入口：把强制复位、平滑复位、组件热复位、最小系统启动、复位原因和复位锁收敛到 bmc.kepler.SystemControl。
• 提供资源树公共查询能力：维护 D-Bus 服务、对象、接口、类和命名对象的索引，供 mdbctl、mc.mdb.mdb_service 和业务组件查询。
• 保护系统可服务性：持续喂硬件看门狗，监控 rsyslog，并在日志文件缺失或服务异常时自愈。
• 支持定制与诊断：持久化 Package 定制属性，提供运行态监控开关、模拟日志和 Debug 采样周期配置。

1.3 核心功能 ​

• 活动组件列表和共享内存 Match 规则管理。
• 启动状态两轮检查、子系统重启和 BMC 自愈复位。
• 健康状态周期检查和组件即时/累计异常重启。
• 组件连续掉线与总掉线次数检查。
• MDB 资源树查询、接口所有者查询、命名对象查询和属性值匹配。
• 强制复位、平滑复位、热复位、复位原因记录和分级复位锁。
• 看门狗喂狗、rsyslog 阻塞检测和日志文件自愈。
• Package 定制信息持久化、配置备份、一键收集 mdb_info.log。

1.4 关键术语表 ​

1.5 外部交互边界图 ​

2. API 使用说明与示例 ​

对外发布的 API 为资源协作接口，服务名 bmc.kepler.maca。路径中的 ManagerId 默认为 1。均可通过 busctl / mdbctl 调试。方法首参 a{ss} 为框架调用上下文；只读调试可传空字典 0。需要 Requestor 的接口应传 1 Requestor <name>。

busctl --user tree bmc.kepler.maca

Lua 业务优先使用 mc.mdb.mdb_service 访问 bmc.kepler.Mdb，不要长期绑定复杂 D-Bus 返回结构。

组件作为微组件还会由 libmc4lua 注册标准 bmc.kepler.MicroComponent* 接口，细节见 libmc4lua，本文不重复。仓库无 mds/ipmi.json，不提供 IPMI 命令。

2.1 bmc.kepler.MCAdmin ​

功能说明 ​

查询活动微组件列表，并在共享内存中添加/删除 D-Bus Match 规则。

路径：/bmc/kepler/MacaService

参数说明 ​

返回值与异常 ​

应用场景 ​

确认组件是否已被 maca 识别；C/C++ 组件由 maca 统一维护共享内存信号订阅。

限制条件 ​

• 列表表示 maca 当前视图，不等同于组件业务完全就绪。
• RemoveMatch 需要与 AddMatch 完全相同的 Requestor 和 MatchString。
• 规则过宽会增加 D-Bus 和共享内存压力。

调试示例 ​

busctl --user call bmc.kepler.maca /bmc/kepler/MacaService \
    bmc.kepler.MCAdmin GetComponentList a{ss} 0

MATCH="type='signal',interface='org.freedesktop.DBus.Properties',member='PropertiesChanged'"
busctl --user call bmc.kepler.maca /bmc/kepler/MacaService \
    bmc.kepler.MCAdmin AddMatch a{ss}s 1 Requestor docs-maca "$MATCH"
busctl --user call bmc.kepler.maca /bmc/kepler/MacaService \
    bmc.kepler.MCAdmin RemoveMatch a{ss}s 1 Requestor docs-maca "$MATCH"

2.2 bmc.kepler.SystemControl ​

功能说明 ​

BMC 强制/平滑复位、组件热复位、复位原因与分级复位锁。

路径：/bmc/kepler/MacaService

参数说明 ​

属性参数说明 ​

ResetLockStatus 取值：Unlocked、WarmResetLocked、GracefulResetLocked、ForceResetLocked。优先级由低到高；高级别被锁定时，低级别复位一并禁止。

方法参数说明 ​

返回值与异常 ​

平滑复位阶段：Prepare → Process → Action。Prepare 明确失败时执行 Cancel 并终止；process/action 明确失败或超时在当前实现中记录后继续。prepare 超时 10 秒，process 默认 120 秒（可配置 120～600 秒），action 超时 60 秒。action 在接口返回成功约 3 秒后开始。

应用场景 ​

升级或维护前平滑复位；异常场景强制复位；BIOS POST 等阶段加复位锁；复位后读取 ResetCause 追溯来源。

限制条件 ​

• 复位类接口风险高，仅在隔离测试机、具备串口和固件恢复手段时执行。
• ForceReset 不等待业务落盘。
• WarmReset 是组件级热复位，不等同于 BMC 重启；任意复位锁级别均会阻止热复位。
• WithCause 方法可能在锁检查之前写入 ResetCause。
• 锁是进程内运行态，maca/framework 重启后不会按源码表自动恢复。

调试示例 ​

busctl --user get-property bmc.kepler.maca /bmc/kepler/MacaService \
    bmc.kepler.SystemControl ResetLockStatus
busctl --user get-property bmc.kepler.maca /bmc/kepler/MacaService \
    bmc.kepler.SystemControl ResetCause

以下复位命令会中断 BMC。请先确认目标、串口和恢复方案，并在提示后输入确认字符串。

read -r -p '输入 RESET-MACA 才执行强制复位: ' confirm
[ "$confirm" = 'RESET-MACA' ] || exit 1
busctl --user call bmc.kepler.maca /bmc/kepler/MacaService \
    bmc.kepler.SystemControl ForceReset a{ss}y 1 Requestor docs-maca 0

CAUSE='The current status does not support the reset operation'
busctl --user call bmc.kepler.maca /bmc/kepler/MacaService \
    bmc.kepler.SystemControl SetResetLockStatus a{ss}ssus \
    1 Requestor docs-maca WarmReset Lock 60 "$CAUSE"
busctl --user call bmc.kepler.maca /bmc/kepler/MacaService \
    bmc.kepler.SystemControl SetResetLockStatus a{ss}ssus \
    1 Requestor docs-maca WarmReset Unlock 10 "$CAUSE"

2.3 bmc.kepler.Dft ​

功能说明 ​

按 Count 连续写入 MOCK LOG STORM=<序号> 的错误日志，用于验证日志风暴抑制与收集链路。

路径：/bmc/kepler/MacaService

参数说明 ​

返回值与异常 ​

无返回值表示注入完成或 Count<=0 时无动作。短时间输出过多可能被框架日志风暴抑制。

应用场景 ​

验证日志限流、一键收集和 rsyslog。

限制条件 ​

调用方必须自行限制 Count；建议从 5～20 条开始。不要在生产环境大规模注入。

调试示例 ​

busctl --user call bmc.kepler.maca /bmc/kepler/MacaService \
    bmc.kepler.Dft MockLogStorm a{ss}u 1 Requestor docs-maca 5

2.4 bmc.kepler.Release.MonitorControl ​

功能说明 ​

在运行态启用或禁用启动检查、健康检查或在线检查。该接口不会修改 mc_control.json。

路径：/bmc/kepler/MacaService

参数说明 ​

返回值与异常 ​

应用场景 ​

故障注入、升级验证、定位检查机制是否导致组件重启或 BMC 自愈。

限制条件 ​

只影响当前运行期，不持久化。关闭监控会降低自愈能力，测试结束必须恢复。

调试示例 ​

busctl --user call bmc.kepler.maca /bmc/kepler/MacaService \
    bmc.kepler.Release.MonitorControl SetMonitorStatus a{ss}sb \
    1 Requestor docs-maca starting true

$ mdbctl
% attach maca
% setmonitorstatus starting false
0

2.5 bmc.kepler.Mdb ​

功能说明 ​

MDB 资源树查询。共享内存没有结果时，部分查询会回退到本地 ObjectMgr。Lua 封装见 mc.mdb.mdb_service。

路径：/bmc/kepler/MdbService

权限：ReadOnly。D-Bus 签名以 libmc4lua 生成代码 mdb.bmc.kepler.Mdb 为准（方法首参均为 Context）。

参数说明 ​

GetSubPaths 只返回带自定义接口的路径；中间目录节点可能在 busctl tree 可见但查询为空，此时应对父对象调用 org.freedesktop.DBus.ObjectManager.GetManagedObjects。

GetTracedObject 已由 libmc4lua 生成代码注册（出参 TracedObjects）。当前工作区 mdb_interface 的 Mdb.json 未列出该方法；调用前请 introspect 确认目标镜像。

maca 1.130.6 仓内文档还记载 GetPropertyMatchedObjects（a{ss}ssvb → a(sssv)，按接口/属性/Variant 匹配，排除 ay 与数组签名）。当前工作区 mdb_interface 与 libmc4lua 生成代码均未收录，本文不把它当作已核实的稳定 API。

返回值与异常 ​

应用场景 ​

按路径/接口枚举对象、分页取子路径、根据类名或对象名反查 Path、配置导入导出时 GetServiceNames。

限制条件 ​

• 查询视图异步维护，服务刚上线时可能短暂为空。
• 只有 well-known name 才进入 MDB；受 MDB_WHITE_LIST / MDB_BLACK_LIST 约束。
• 根路径深层查询开销较大，避免高频轮询。
• GetPath 的 Filter 序列化时最好保证键顺序稳定（Lua 封装会缓存）。

调试示例 ​

busctl --user call bmc.kepler.maca /bmc/kepler/MdbService \
    bmc.kepler.Mdb GetServiceNames a{ss} 0

busctl --user call bmc.kepler.maca /bmc/kepler/MdbService \
    bmc.kepler.Mdb GetObject a{ss}sas 0 /bmc/kepler/MacaService 1 bmc.kepler.SystemControl

busctl --user call bmc.kepler.maca /bmc/kepler/MdbService \
    bmc.kepler.Mdb GetSubPaths a{ss}sias 0 /bmc/kepler 1 0

busctl --user call bmc.kepler.maca /bmc/kepler/MdbService \
    bmc.kepler.Mdb IsValidPath a{ss}sb 0 /bmc/kepler/MacaService false

local mdb_service = require 'mc.mdb.mdb_service'
local rsp = mdb_service.get_service_names(bus)
local obj = mdb_service.get_object(bus, '/bmc/kepler/MacaService', 'bmc.kepler.SystemControl')

2.6 bmc.kepler.Managers.Package ​

功能说明 ​

读取或设置 BMC 包定制信息。属性保存到本地 PoweroffPer 数据库（t_package）。

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

参数说明 ​

读权限 ReadOnly，写权限 BasicSetting。写入 Version 且存在调用 Context 时会记录操作日志 Set customized version successfully。

返回值与异常 ​

读取成功返回字符串。写入失败时检查权限、maca.db 和 operation/framework 日志。

应用场景 ​

读取或更新 BMC 包定制信息。

限制条件 ​

• 不要把 maca 组件自身版本写入 Version。
• 源码未定义长度或枚举约束（Customer 枚举限制已移除）；业务格式由产品定制规范定义。
• 频繁写入应考虑闪存寿命。修改前记录原值，测试后恢复。

调试示例 ​

busctl --user get-property bmc.kepler.maca /bmc/kepler/Managers/1/Package \
    bmc.kepler.Managers.Package Customer
busctl --user get-property bmc.kepler.maca /bmc/kepler/Managers/1/Package \
    bmc.kepler.Managers.Package Version
busctl --user get-property bmc.kepler.maca /bmc/kepler/Managers/1/Package \
    bmc.kepler.Managers.Package Provider

2.7 Debug 接口 ​

功能说明 ​

仅 Debug 构建、且相关模块可加载时出现。community 模式下当前实现即使加载 Debug 服务也不创建 LogMock 对象。

路径：

• /bmc/kepler/Debug/LogMock — bmc.kepler.Debug.LogMock.MockLog
• /bmc/kepler/Debug/Performance — bmc.kepler.Debug.Performance.PerformanceSamplingIntervalMinutes

参数说明 ​

RepeatText=true 时重复输出完全相同文本；false 时追加 (seq=n)。

返回值与异常 ​

UnknownObject 表示对象不存在（Release、community 裁剪或模块未加载）。Count/Text 越界由模型校验拒绝。

应用场景 ​

Debug 镜像验证重复日志合并、风暴抑制和性能采样周期。

限制条件 ​

日志内容不得包含口令、密钥或个人数据。不要一次使用 Count 上限。

调试示例 ​

busctl --user introspect bmc.kepler.maca /bmc/kepler/Debug/LogMock
busctl --user call bmc.kepler.maca /bmc/kepler/Debug/LogMock \
    bmc.kepler.Debug.LogMock MockLog a{ss}usb 1 Requestor docs-maca 3 'maca-doc-test' false

busctl --user get-property bmc.kepler.maca /bmc/kepler/Debug/Performance \
    bmc.kepler.Debug.Performance PerformanceSamplingIntervalMinutes

3. 组件扩展案例 ​

3.1 扩展能力概述 ​

maca 的主要扩展点不在于向 maca 仓直接添加业务代码，而在于让其他组件通过统一元数据和回调接入生命周期管理：

1. 在 service.json 声明 type: application 和 deployConfig。
2. 注册 MicroComponent 健康检查回调。
3. 实现平滑复位 / 热复位回调。
4. 通过 mc_control.json 调整监控阈值和 process 超时。
5. 配置 MDB 白名单 / 黑名单。
6. 使用 mc.mdb.mdb_service 查询资源树。

3.2 扩展点说明 ​

3.3 二次开发指导 ​

步骤一：声明组件元数据 ​

{
  "name": "demo_component",
  "type": "application",
  "deployConfig": "demo_subsystem.service",
  "version": "1.0.0",
  "author": "openUBMC",
  "license": "Mulan PSL v2",
  "description": "demo component",
  "dependencies": {},
  "required": []
}

type 不是 application 时不进入常驻检查范围。不要把业务组件错误映射到 framework.service。

步骤二：注册健康检查 ​

local micro_component = require 'mc.mdb.micro_component'

micro_component.on_health_check(function(ctx)
    if fatal_condition() then
        return micro_component.HEALTH.NEED_RESTART_NOW
    end
    if transient_condition() then
        return micro_component.HEALTH.ABNORMAL
    end
    return micro_component.HEALTH.NORMAL
end)

步骤三：实现平滑复位回调 ​

local reboot = require 'mc.mdb.micro_component.reboot'

reboot.on_prepare(function(ctx)
    return prepare_for_reboot() and 0 or -1
end)

reboot.on_process(function(ctx)
    return persist_state() and 0 or -1
end)

reboot.on_action(function(ctx)
    return close_resources() and 0 or -1
end)

reboot.on_cancel(function(ctx)
    rollback_prepare()
end)

Prepare 返回 -1 时调用方收到 ResetOperationNotAllowed，组件收到 Cancel。Process/Action 失败或超时仍可能继续 BMC 复位。回调必须幂等。

步骤四：运行参数 ​

默认配置文件 /opt/bmc/conf/mc_control.json。可配置项包括 starting_monitor.startup_check、running_monitor.health_check / offline_check、graceful_reset_config.process.timeout_seconds（120～600）。环境变量还可覆盖 MC_CONTROL_PATH、MDB_WHITE_LIST、MDB_BLACK_LIST、CONTINUOUS_OFFLINE_TIMES、MAX_RESTART_LIMIT 等。

MDB 默认 MDB_WHITE_LIST="^i?bmc"。黑名单按完整名称精确匹配并优先拒绝；白名单按 Lua pattern 匹配。

验证方法 ​

1. GetComponentList 确认组件在活动列表。
2. 查看 /var/log/framework.log 中 startup/health 日志。
3. 故障注入后确认只重启预期 deployConfig。
4. 修改白名单后用 GetServiceNames 核对索引范围。

注意事项 ​

• 健康回调需快速返回；maca RPC 超时为 30 秒，但业务不应把该上限当作正常耗时。
• StartupCheck failed 只是 maca 观察到的结果，根因可能在上游依赖。
• 保持接口名、错误消息 ID 向后兼容；不得在日志中输出密钥或口令。

4. 日志说明 ​

4.1 一键日志收集 ​

maca 通过 MicroComponent Debug 的 on_dump 输出：

配置备份回调会把 maca.db 复制到调用方指定目录，属于配置备份链路，不要与一键日志文件混为一谈。

4.2 关键日志信息 ​

临时提升调试级别：

busctl --user call bmc.kepler.maca /bmc/kepler/maca/MicroComponent \
    bmc.kepler.MicroComponent.Debug SetDlogLevel a{ss}sy 0 debug 1

MicroComponent 实际路径以目标镜像 introspect 为准。完成后恢复 notice。

5. 问题定界指南 ​

5.1 典型问题定界 ​

5.2 错误码速查表 ​

5.3 最小化复现与证据收集 ​

1. 记录服务名、对象路径、接口、方法、Context、返回值和 ResetLockStatus。
2. 收集 framework.log、app.log、operation.log、running.log 与 mdb_info.log。
3. systemctl status framework.service maca.service，并用 busctl --user tree/introspect/call 交叉验证。
4. 无自定义接口的路径改用 GetManagedObjects。
5. 保存固件版本、maca 版本、是否最小系统、mc_control.json 和相关环境变量。

systemctl status framework.service maca.service --no-pager
busctl --user tree bmc.kepler.maca
busctl --user introspect bmc.kepler.maca /bmc/kepler/MacaService
busctl --user introspect bmc.kepler.maca /bmc/kepler/MdbService
busctl --user call bmc.kepler.maca /bmc/kepler/MacaService \
    bmc.kepler.MCAdmin GetComponentList a{ss} 0

5.4 调试方法 ​

• 复位与监控开关只在可恢复的测试 BMC 上操作；先记录原值，结束后恢复。
• 不要同时测试启动失败、连续掉线和复位，避免多种自愈机制交叠。
• 业务查询优先 require 'mc.mdb.mdb_service'；直接 D-Bus 用于现场交叉验证。

6. 常见问题解答 ​

Q1：为什么 StartupCheck failed 不一定是 maca 的缺陷？ ​

• 问题描述：启动检查报组件失败。
• 一句话答案：maca 只是在规定窗口内没有观察到组件完成初始化。
• 根因说明：目标组件可能因上游依赖、配置、硬件或 systemd dependency failed 没有启动。
• 解决方案：先查目标 deployConfig 和依赖树，再查 maca 策略与阈值。
• 规避方案：把 abnormal component 当作排查入口，不当作根因结论。
• 适用版本：1.130.9。

Q2：GracefulReset 返回 0 是否表示所有组件都成功保存数据？ ​

• 问题描述：平滑复位返回成功，但有组件数据未落盘。
• 一句话答案：不是。它主要表示 prepare 被接受并启动后续流程。
• 根因说明：当前 process/action 失败或超时会记录后继续复位。
• 解决方案：检查 prepare/process/action 各阶段组件日志和耗时。
• 规避方案：关键组件应在 Prepare 前置校验，并实现可靠、幂等的 Process/Action。
• 适用版本：1.100.8 及以后。

Q3：为什么 GetSubPaths 查不到 busctl tree 里能看到的路径？ ​

• 问题描述：tree 看得到路径，MDB 查询返回空。
• 一句话答案：该方法只返回带自定义接口的路径。
• 根因说明：中间目录节点可能没有业务接口。
• 解决方案：对父对象调用 org.freedesktop.DBus.ObjectManager.GetManagedObjects。
• 规避方案：为该节点补充接口，或在业务侧改用 GetManagedObjects。
• 适用版本：1.130.9。

Q4：MDB 查询不到对象，但组件 D-Bus 服务存在？ ​

• 问题描述：busctl list 有服务名，GetServiceNames / GetObject 没有对应对象。
• 一句话答案：检查 MDB 白名单/黑名单以及服务是否为 well-known name。
• 根因说明：默认 MDB_WHITE_LIST="^i?bmc"；黑名单精确匹配优先拒绝；非 well-known name 不进入 MDB。
• 解决方案：核对环境变量与服务名，用 GetServiceNames 确认索引范围。
• 规避方案：变更信任列表后重启承载 maca 的实际子系统，不要只假设存在独立 maca.service。
• 适用版本：1.130.9。

Q5：AddMatch / RemoveMatch 报 Requestor 错误？ ​

• 问题描述：Match 规则接口失败。
• 一句话答案：Context 必须携带字符串 Requestor，删除时须与添加时完全一致。
• 根因说明：共享内存规则以 Requestor + MatchString 为幂等键。
• 解决方案：使用 1 Requestor <稳定标识>，MatchString 逐字一致。
• 规避方案：组件退出前主动 RemoveMatch，避免残留规则。
• 适用版本：1.10.16 及以后。