event_policy（事件策略） ​

版本信息 ​

1. 组件概述 ​

1.1 组件简介 ​

event_policy 是 openUBMC 中的事件策略服务。服务从 event 组件读取 Event 和 SEL 记录，将符合事件通道、类型及严重度配置的记录分发到 SNMP Trap、SMTP 和 Syslog 通道，并对处于 Asserted 状态的事件执行其 ActionId 指定的主机电源动作。

服务还负责启动时补报未处理记录、未恢复告警重上报（Rearm）、配置持久化、OEM IPMI 命令注册以及可选的跨板事件同步。Redfish 订阅配置对象仍由本组件创建，但源码已明确将 Redfish 告警上报逻辑迁移到 redfish 组件，本组件不直接发送 Redfish 事件。

1.2 解决什么问题 ​

• 统一接收 Event 和 SEL，避免事件产生方分别实现外部告警上报。
• 为 SNMP、SMTP 和 Syslog 提供统一的使能、过滤、接收端和凭据配置。
• 从已持久化的记录号继续同步，降低服务重启造成的漏报风险。
• 根据事件策略执行强制下电、强制重启或下电再上电。
• 在双节点场景中向对端同步事件及通道位置数据。

1.3 核心功能 ​

• 事件同步与监听：监听 EventRecordSeq 和 RecordSeq，同步新产生及停机期间遗漏的 Event/SEL。
• 多通道上报：按 ReportChannel、EventType、使能状态和 SeverityFilter 分发事件。
• SNMP 配置：支持 SNMPv1、SNMPv2c、SNMPv3，NMS、SNMP Destination、团体名、Trap 模式和服务器标识配置。
• SMTP 配置：支持服务器、TLS、认证/匿名模式、发件人、最多四个收件人、主题和测试邮件。
• 事件策略：仅对告警产生的事件根据ActionId判断是否要执行对应的主机电源动作。
• 事件重上报：将未恢复告警重新投递到指定通道或全部通道。
• 配置管理：注册配置导入、导出和可信配置回调，敏感值通过 KMC 加密后持久化。
• Trap 插件：按客户名加载 Lua 插件，替换 SNMP Trap OID 和 bindings 封装逻辑。

1.4 关键术语表 ​

1.5 外部交互边界图 ​

mds/service.json 还声明了证书、网络、FRU、机箱等必选或可选资源接口；上图仅展示主处理链路。Syslog 远端配置由 bmc.kepler.Managers.Syslog 依赖提供，本组件通过 syslog.core 提交消息。

1.6 构建、测试与部署 ​

工具与依赖 ​

• CMake 最低版本为 3.14，Conan 最低版本为 2.13.0。
• 构建依赖包含 libmc4lua 和 lsnmp；DT（Developer Test）测试依赖清单见 mds/service.json 的 dependencies.test。

测试入口 ​

bingo test

该命令依赖 openUBMC DT 环境、Lua/Skynet 运行时及组件依赖，不能视为在普通源码检出中可直接运行。单元、集成和 fuzz 用例分别位于 test/unit、test/integration 和 test/fuzz。

安装与启动 ​

• 安装目录：/opt/bmc/apps/event_policy。
• systemd 单元：event_policy.service。
• 工作目录：/opt/bmc/apps/event_policy。
• 启动命令：/opt/bmc/skynet/skynet /opt/bmc/apps/event_policy/config.cfg。
• 服务异常退出后自动重启，间隔为 1 秒。
• systemd 依赖 dbus.service、framework.service、persistence.service、key_mgmt.service 和 event.service。

2. API 使用说明与示例 ​

本组件对外提供 D-Bus 资源接口和 OEM IPMI 命令。D-Bus 服务名为 bmc.kepler.event_policy，运行配置使用 user bus，以下命令统一带 --user。类型 b、y、q、t、s、as 分别表示布尔、无符号 8 位、无符号 16 位、无符号 64 位、字符串和字符串数组。

2.1 D-Bus 配置与控制接口 ​

功能说明 ​

D-Bus 模型定义以 mds/model.json 为准，需要查看接口时，可按对象名搜索该文件；例如下面的命令可定位 SNMP 配置，继续查看其 interfaces、properties、methods 和 signals：

rg -n -A 120 '^    "Snmp":' mds/model.json

模型经代码生成后由 gen/event_policy/service.lua 注册；生成文件适合核对运行时签名，但不应直接修改。以 SNMP 配置为例，mds/model.json 当前定义的对象路径为 /bmc/kepler/EventService/Subscriptions/Snmp，接口为 bmc.kepler.EventService.Subscriptions.Snmp。

参数说明 ​

SNMP 团体名仅适用于 SNMPv1/v2c。关闭密码复杂度检查时长度为 1～32 且不得含空格；开启复杂度检查时长度为 8～32，并须通过系统复杂度校验。

返回值与异常 ​

应用场景 ​

用于配置上报端点和过滤条件、发送测试事件，以及对未恢复事件执行 Rearm。SyncEvent 由双节点内部 CNC 链路调用。

限制条件 ​

• EventSync.SyncEvent 是跨板内部协作接口，不建议作为人工调试接口。
• SMTP 非匿名模式修改服务器地址、匿名状态或用户名时，可能要求先在同一配置流程中更新密码。
• SMTP 用户名长度为 1～64，密码长度为 1～50，邮箱及主题相关字符串最大 255 字符。
• 默认数据包含 4 个 NMS 和 4 个 SMTP Receiver，ID 为 1～4。

调试示例 ​

命令行调试 ​

# 读取 SNMP 版本
busctl --user get-property \
  bmc.kepler.event_policy \
  /bmc/kepler/EventService/Subscriptions/Snmp \
  bmc.kepler.EventService.Subscriptions.Snmp Version

# 设置严重度过滤掩码为 12
busctl --user call \
  bmc.kepler.event_policy \
  /bmc/kepler/EventService/Subscriptions/Snmp \
  org.freedesktop.DBus.Properties Set \
  ssv bmc.kepler.EventService.Subscriptions.Snmp SeverityFilter y 12

# 为 SNMPv1/v2c 设置团体名
busctl --user call \
  bmc.kepler.event_policy \
  /bmc/kepler/EventService/Subscriptions/Snmp \
  bmc.kepler.EventService.Subscriptions.Snmp SetCommunity \
  'a{ss}s' 3 Interface CLI UserName Administrator ClientIp 127.0.0.1 'Admin@9000'

# 向第一个 NMS 发送测试事件
busctl --user call \
  bmc.kepler.event_policy \
  /bmc/kepler/EventService/Subscriptions/Snmp/Nmses/1 \
  bmc.kepler.EventService.Subscriptions.Snmp.Nms SubmitTestEvent \
  'a{ss}' 3 Interface CLI UserName Administrator ClientIp 127.0.0.1

# 将未恢复事件重报到 SNMP Trap 和 SMTP
busctl --user call \
  bmc.kepler.event_policy \
  /bmc/kepler/EventService/Event \
  bmc.kepler.EventService.Event Rearm \
  'a{ss}as' 3 Interface CLI UserName Administrator ClientIp 127.0.0.1 \
  2 SNMPTrap Smtp

2.2 OEM IPMI 命令 ​

功能说明 ​

组件按 mds/ipmi.json 注册 LAN 参数和 OEM 命令，用于查询或设置 NMS、SNMP 团体名、Trap 版本/严重度/使能、事件类型、测试 Trap 和 Rearm。

参数说明 ​

命令的 netfn、cmd、请求字段、响应字段和权限均由 mds/ipmi.json 定义。可先查询模型：

rg -n -A 70 '^        "GetAlertDestNum":' mds/ipmi.json

返回值与异常 ​

命令成功时返回标准 IPMI 完成码 0x00；参数、权限、长度或状态错误返回 5.2 节列出的非零完成码。

应用场景 ​

供 IPMI 客户端查询或配置告警目标、SNMP 参数和事件上报策略。

限制条件 ​

实际调用必须满足相应的 User/Operator 角色和 ReadOnly/BasicSetting 权限；标记 sysLockedPolicy: Forbidden 的写命令在系统锁定时不可调用。

调试示例 ​

优先在测试设备上使用与实际调用一致的命令参数，避免直接对生产设备执行写操作。模型查询方式如下：

rg -n -A 70 '^        "GetAlertDestNum":' mds/ipmi.json

3. 组件扩展案例 ​

3.1 扩展能力概述 ​

组件提供 SNMP Trap Lua 插件扩展点，可替换事件、SEL 和测试 Trap 的企业 OID 及 bindings 封装逻辑。除此之外，仓库未定义通用插件框架。

3.2 扩展点说明 ​

src/lualib/libpolicy/plugin_mgmt.lua 读取 /bmc/kepler/Managers/1/Package 的 Customer 属性，并执行 require(Customer .. '.apps.trap_plugin')。结合 /opt/bmc/extend/?.lua 搜索路径，实际文件路径为：

/opt/bmc/extend/<Customer>/apps/trap_plugin.lua

插件加载失败或模块不存在时，代码静默使用内置实现，不会阻止服务启动。

3.3 二次开发指导 ​

步骤一 ​

复制 example/trap_plugin.lua，保留五个函数的模块接口，并按目标 MIB 修改 OID、字段值和 SNMP 类型字符。

步骤二 ​

部署到 /opt/bmc/extend/<Customer>/apps/trap_plugin.lua；<Customer> 必须与 Package 对象的 Customer 属性完全一致。随后重启 om 进程。完整实现请直接参考仓库中的 example/trap_plugin.lua。

验证方法 ​

1. 参考 openUBMC 社区的 SNMP Trap 上报测试环境搭建指南 在与 BMC 网络互通的 Windows 主机安装 MIB Browser，并在 Trap Ringer Console 配置监听地址和端口。免费版本仅适合验证 SNMPv1/v2c；验证 SNMPv3 时需使用支持 SNMPv3 的版本。
2. 在 BMC Web 界面的“维护诊断 > 告警上报 > SNMP 报文通知”中，将 NMS 地址设为接收端主机 IP，端口设为 Trap Ringer Console 的监听端口，并启用对应配置。SNMPv3 还需在“用户&安全 > 本地用户”中为 V3 用户配置加密密码和算法，并在接收端配置相同的用户、鉴权及加密参数。
3. 部署插件并重启 om 进程后，在 SNMP 报文通知页面点击对应 NMS 的“测试”按钮；随后产生一条满足上报通道、事件类型和严重度过滤条件的真实告警。
4. 在 Trap Ringer Console 中分别确认测试 Trap 和真实告警 Trap 已到达，并核对企业 OID、bindings、值及 SNMP 类型是否符合插件实现。Trap 是单向协议，BMC 侧测试操作成功不等于接收端一定收到报文，应以接收端结果为准。

注意事项 ​

• require 会将模块名中的点转换为目录分隔，必须按上文所示的 <Customer>/apps/ 两级目录部署。
• bindings 的每项格式为 {oid_table, value, type}。
• 插件函数缺失时对应注册项为空，应实现并测试全部五个函数。
• 源码没有插件加载成功/失败日志，应以测试 Trap 内容判断是否生效。

4. 日志说明 ​

4.1 一键日志收集 ​

组件未注册自定义 on_dump 回调，一键日志按框架默认逻辑收集。诊断时应同时保留 event_policy 的标准日志、event 组件事件记录和相关配置属性。

4.2 关键日志信息 ​

5. 问题定界指南 ​

5.1 典型问题定界 ​

5.2 错误码速查表 ​

以下完成码定义于 src/lualib/ipmi/base.lua，仅适用于 OEM IPMI 路径；D-Bus 失败返回框架错误对象。

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

1. 记录事件对象、EventCode、State、ReportChannel、EventType 和 SeverityFilter。
2. 使用测试 Trap 或测试邮件接口验证通道链路，并与真实事件配置逐项比较。
3. 收集 event_policy、event、SNMP/SMTP 对应服务和 persistence 日志。
4. 主机电源动作问题还应收集 ActionId、FruCtrl 和 PowerCtrl 返回结果。

5.4 调试方法 ​

• 在测试环境先验证 SNMP Trap、SMTP、Syslog 三类通道，再切换到真实事件。
• 使用 busctl --user 读取配置属性和错误对象。
• 开启相关组件调试日志后复现，禁止在未确认影响时执行写操作。

6. 常见问题解答 ​

Q1：为什么设置 SNMP 团体名失败？ ​

• 问题描述：SetCommunity 返回参数或复杂度错误。
• 一句话答案：团体名必须满足当前 SNMP 版本、长度、空格和复杂度规则。
• 根因说明：校验会检查当前版本、长度、空格和复杂度策略。
• 解决方案：确认版本为 SNMPv1/v2c，并按 2.1 节规则调整团体名。
• 规避方案：配置前读取当前版本与密码复杂度策略。
• 适用版本：1.140.13。

Q2：已收到事件但网管没有收到告警，如何定位？ ​

• 问题描述：event 或 SEL 记录已经产生，但目标通道没有上报。
• 一句话答案：先核对事件通道位、事件类型、使能状态和严重度过滤，再检查通道发送错误。
• 根因说明：事件分发受 ReportChannel、EventType、使能和 SeverityFilter 共同控制。
• 解决方案：读取事件字段和订阅对象属性，使用测试 Trap/邮件确认链路，再逐项比对真实事件配置。
• 规避方案：上线前同时验证测试告警和真实告警，并保存配置原值。
• 适用版本：1.140.13。

Q3：SMTP 测试失败或真实邮件未发送，如何处理？ ​

• 问题描述：邮件通道测试失败，或事件触发后没有收到邮件。
• 一句话答案：优先检查 SMTP 地址、端口、TLS、认证、发件人和收件人配置。
• 根因说明：SMTP 连接、认证、TLS 协商和收件人校验失败都会阻止发送。
• 解决方案：调用收发件人测试接口，检查 send a event email to SMTP server failed 日志和相关属性。
• 规避方案：修改服务器或凭据前先导出配置，在维护窗口完成验证。
• 适用版本：1.140.13。

Q4：配置的 ActionId 没有触发主机电源动作，如何排查？ ​

• 问题描述：事件已产生，但没有执行强制下电、重启或下电再上电。
• 一句话答案：确认事件处于 Asserted 状态、ActionId 有效，并检查 FruCtrl 执行结果。
• 根因说明：组件只对符合策略的产生事件执行 ActionId，执行失败时资源协作接口会返回错误。
• 解决方案：收集 EventCode、State、ActionId 和 execute the strategy of event 日志，核对 FruCtrl/PowerCtrl。
• 规避方案：启用电源动作前先在测试环境验证事件策略和恢复路径。
• 适用版本：1.140.13。

社区资料 ​

更多 event_policy 组件说明及相关服务测试环境搭建方法，可在 openUBMC 社区文档中心搜索 event_policy、SNMP Trap、SMTP 或 rsyslog，也可直接参考：

• event_policy 组件说明
• SNMP Trap 上报测试环境搭建指南
• SMTP 测试环境搭建指南
• rsyslog 服务器搭建指导