lsnmp ​

版本信息 ​

1. 组件概述 ​

1.1 组件简介 ​

lsnmp 是 openUBMC 平台中的 Lua 动态库组件，用于封装 net-snmp 的部分 C API。组件将 SNMP Trap 发送以及 SNMPv3 密钥派生能力暴露为 Lua 函数和 Lua 可访问的数据结构，供告警上报、事件通知和 SNMP 用户密钥管理等上层业务使用。

组件类型为 library，编译产物为 lsnmp.so，默认安装到 /opt/bmc/luaclib。它不启动独立进程、不注册 D-Bus 服务，也不维护独立配置模型；实际代码运行在调用该库的宿主进程内。

1.2 解决什么问题 ​

上层 Lua 业务若直接调用 net-snmp，需要自行处理 Lua/C 数据转换、SNMP 会话初始化、PDU 构造、SNMPv3 鉴权与加密参数配置以及 Ku/Kul 密钥派生。lsnmp 对这些公共操作进行统一封装，使业务组件可以在 Lua 层完成以下工作：

• 构造并发送 SNMPv1、SNMPv2c 或 SNMPv3 Trap。
• 根据口令和鉴权算法生成 SNMPv3 Ku。
• 根据 Ku 和 EngineID 生成本地化密钥 Kul。
• 复用一致的参数校验、错误返回和日志输出方式。

1.3 核心功能 ​

• Trap 发送：通过 send_snmp_trap_msg 构造变量绑定并发送 SNMPv1、SNMPv2c 或 SNMPv3 Trap。
• Ku 生成：通过 generate_ku 根据口令和鉴权协议生成 SNMPv3 用户密钥 Ku。
• Kul 生成：通过 generate_kul 将 Ku 与指定 EngineID 绑定，生成本地化密钥 Kul（接口字段名为 pwd_key）。
• Lua 数据类型封装：提供 SNMP_TRAP_MSG、GEN_KU_STRU、GEN_KUL_STRU 三种数据结构及其 zero() 方法。

1.4 关键术语表 ​

1.5 外部交互边界图 ​

构建时依赖 libmc4lua >= 1.1.0 和 net-snmp >= 5.9.3。运行时的网络通信和日志归属宿主进程；组件自身没有常驻进程、监听端口或 D-Bus 交互面。

2. API 使用说明与示例 ​

安装后使用以下方式加载模块：

local lsnmp = require 'lsnmp_core'

模块导出三个函数和三个数据结构。以下接口均为 Lua 本地接口，不是资源协作接口，不能通过 busctl 调用。

2.1 send_snmp_trap_msg ​

功能说明 ​

按照输入的 Trap 参数、变量绑定和企业 OID 构造并发送一条 SNMP Trap，支持 SNMPv1、SNMPv2c 和 SNMPv3。

函数签名：

local ret = lsnmp.send_snmp_trap_msg(snmp_trap_msg, bindings, oid)

参数说明 ​

bindings 子项的格式如下：

返回值与异常 ​

应用场景 ​

• BMC 告警或事件通过 Trap 上报到网管系统。
• 发送测试 Trap，验证目的管理站、网络和 SNMP 参数配置。
• 上层 Lua 服务复用统一的 SNMPv3 鉴权加密发送能力。

限制条件 ​

• version 仅接受 SNMPv1、SNMPv2c、SNMPv3，区分大小写。
• 目的地址可为 IPv4、IPv6 或可解析域名；IPv6 链路本地地址应通过 veth 提供作用域后缀，例如 %eth0。
• SNMPv1/SNMPv2c 使用 community；SNMPv3 固定按 authPriv 安全级别初始化，需要用户名、鉴权/加密协议、对应密钥和可读取的 snmpd 配置文件。
• SNMPv3 的 authentication_key 和 encryption_key 为不带 0x 前缀的十六进制字符串，至少包含 2 个字符；应使用与协议匹配的有效密钥长度。
• SNMPv3 用户名内部缓冲区为 32 字节，用户名必须能完整写入该缓冲区。
• 会话超时固定为 1 秒，重试次数固定为 3 次。
• 组件使用进程内静态状态保存部分 SNMPv3 和 OID 数据，调用方不应并发调用 send_snmp_trap_msg。

调试示例 ​

Lua 调试 ​

local lsnmp = require 'lsnmp_core'

local trap = lsnmp.SNMP_TRAP_MSG()
trap.version = 'SNMPv2c'
trap.address = '192.168.1.100'
trap.port = 162
trap.community = 'public'
trap.is_test_event = true
trap.veth = ''
trap.agent_address = '0.0.0.0'

local bindings = {
    {{1, 3, 6, 1, 4, 1, 9999, 1}, 'alarm test message', 's'},
}
local enterprise_oid = {1, 3, 6, 1, 4, 1, 9999, 1}

local ret = lsnmp.send_snmp_trap_msg(trap, bindings, enterprise_oid)
print('send result:', ret)

2.2 generate_ku ​

功能说明 ​

根据用户口令和鉴权协议生成 SNMPv3 Ku。鉴权用途与加密用途的 Ku 均按鉴权协议派生。

函数签名：

local ret = lsnmp.generate_ku(gen_ku)

参数说明 ​

返回值与异常 ​

应用场景 ​

为 SNMPv3 用户生成鉴权或加密使用的 Ku，或作为 generate_kul 的输入。

限制条件 ​

• ku 是二进制字符串，可能包含 \0，不得使用只适用于文本的处理方式截断它。
• 源码在口令少于 8 字符时仍以最小长度 8 调用 net-snmp，但这会读取超出口令实际长度的数据并使结果不可预期；调用方必须保证口令长度不少于 8 字符。
• 对未识别的鉴权协议枚举，底层当前会回退到 SHA512。调用方仍应只使用 2.5 节列出的有效非零鉴权算法，避免配置与计算结果不一致。

调试示例 ​

Lua 调试 ​

local lsnmp = require 'lsnmp_core'

local gen = lsnmp.GEN_KU_STRU()
gen.protocol = 2
gen.pwd = 'MyPassword'

local ret = lsnmp.generate_ku(gen)
print('generate_ku result:', ret, 'ku length:', #gen.ku)

2.3 generate_kul ​

功能说明 ​

根据 Ku、鉴权协议和 EngineID 生成 SNMPv3 本地化密钥 Kul。成功结果通过十六进制字符串字段 pwd_key 返回。

函数签名：

local ret = lsnmp.generate_kul(gen_kul)

参数说明 ​

返回值与异常 ​

应用场景 ​

把用户 Ku 本地化到具体的 SNMP Engine，用于 SNMPv3 Trap 的鉴权密钥或加密密钥配置。

限制条件 ​

• 当前实现固定按 13 字节 EngineID 参与计算，因此 engine_id 必须为 0x 加 26 位十六进制字符。
• ku 必须直接使用 generate_ku 的二进制输出，且生成 Ku/Kul 使用的 protocol 必须一致。
• pwd_key 是不带 0x 前缀的十六进制字符串。

调试示例 ​

Lua 调试 ​

local lsnmp = require 'lsnmp_core'

local gen_ku = lsnmp.GEN_KU_STRU()
gen_ku.protocol = 2
gen_ku.pwd = 'MyPassword'
assert(lsnmp.generate_ku(gen_ku) == 0)

local gen_kul = lsnmp.GEN_KUL_STRU()
gen_kul.protocol = 2
gen_kul.ku = gen_ku.ku
gen_kul.engine_id = '0x80001f8880aabbccddeeff1234'

local ret = lsnmp.generate_kul(gen_kul)
print('generate_kul result:', ret, 'pwd_key:', gen_kul.pwd_key)

2.4 数据结构说明 ​

2.4.1 SNMP_TRAP_MSG ​

方法 zero() 会对结构对象占用的内存做清零。由于结构包含 C++ std::string 成员，业务代码不应把 zero() 当作常规重置方法使用；需要重置时建议重新创建对象并逐项赋值。

2.4.2 GEN_KU_STRU ​

2.4.3 GEN_KUL_STRU ​

2.5 协议/算法枚举 ​

鉴权协议枚举适用于 authentication_protocol、GEN_KU_STRU.protocol 和 GEN_KUL_STRU.protocol：

加密协议枚举适用于 encryption_protocol：

3. 组件扩展案例 ​

3.1 扩展能力概述 ​

lsnmp 不提供插件机制、配置 DSL 或运行时扩展点。mds/service.json 的 required 为空，仓库中也没有 model.json 或 ipmi.json。组件支持的扩展方式是代码级二次开发：

• 上层组件增加对 lsnmp 的构建/运行依赖后调用现有 Lua API。
• 在 lsnmp 中新增 C/C++ 封装函数或数据结构，并通过 lsnmp_core 模块导出。

3.2 扩展点说明 ​

3.3 二次开发指导 ​

步骤一：实现 C/C++ 入口 ​

在 src 目录中实现新能力，使用 gint32 返回状态；对输入进行校验，并通过 debug_log 记录可定位但不泄露密钥或口令的信息。

步骤二：注册 Lua API ​

在头文件声明入口，并在 src/l_snmp.cpp 的 lsnmp_init 中注册。例如新增 query_feature：

t.set("query_feature", c_func_wrap(L, l_query_feature));

如需新的 Lua 数据结构，在 src/l_type_register.cpp 中使用 luawrap::lua_class 注册。

示例代码 ​

上层组件使用现有能力时，应先在其依赖清单中声明 lsnmp，再加载模块：

local lsnmp = require 'lsnmp_core'

local request = lsnmp.GEN_KU_STRU()
request.protocol = 4
request.pwd = 'StrongPassword'
assert(lsnmp.generate_ku(request) == 0)

验证方法 ​

1. 使用项目构建环境编译，确认生成无 lib 前缀的 lsnmp.so。
2. 将产物安装到 Lua C 模块搜索路径，执行 require 'lsnmp_core'。
3. 调用新增 API 的成功、非法参数和底层失败场景。
4. 预期成功场景返回 0，失败场景返回明确错误或抛出文档化异常，并产生不包含敏感信息的定位日志。

注意事项 ​

• 保持 Lua 导出名称、结构字段名称和错误语义向后兼容。
• 不得在日志中输出口令、Ku、Kul、鉴权密钥或加密密钥。
• 组件存在进程内静态状态；修改发送路径时需重点评估并发安全和多宿主调用影响。
• 新增算法时需同步确认 net-snmp 版本、OID 长度和密钥长度要求。
• 若新增 API，须同步更新本文档的 API、错误码、日志和 FAQ 章节。

4. 日志说明 ​

4.1 一键日志收集 ​

lsnmp 是动态库，不创建独立日志文件，也没有仓库内声明的独立一键日志收集项。源码通过 debug_log 写入调用它的宿主进程日志，因此系统执行一键日志收集时，是否收集到这些日志以及对应文件路径由宿主组件的日志配置决定。

4.2 关键日志信息 ​

5. 问题定界指南 ​

5.1 典型问题定界 ​

5.2 错误码速查表 ​

5.3 调试方法 ​

开启调试日志 ​

组件没有独立日志级别开关。应在宿主进程或系统日志配置中开启 DEBUG 级别，再按 lsnmp 源码日志关键字过滤。不要为排障打印口令、Ku、Kul 或 SNMPv3 密钥。

复现问题方法 ​

1. 确认 /opt/bmc/luaclib/lsnmp.so 可被 require 'lsnmp_core' 加载。
2. 使用第 2 章最小示例，先验证 generate_ku 和 generate_kul，再验证 Trap 发送。
3. 对发送问题，在管理站监听 UDP 162，并在发送端执行 tcpdump -ni any udp port 162。
4. 预期 API 返回 0；发送端能观察到发往配置地址/端口的 UDP 报文，管理站能解析相同版本和凭据的 Trap。

lsnmp 没有 D-Bus 对象，因此不存在 busctl 命令行调试方式；应使用 Lua 脚本和网络抓包。

5.4 错误对象解读 ​

lsnmp 的 Lua API 返回整数 rc 或字符串结果，不使用 D-Bus 结构化错误对象。0 表示成功，-1 表示参数、内存或底层库调用失败，其他返回值按 5.2 节错误码表解释。

6. 常见问题解答 ​

Q1：为什么 require 'lsnmp_core' 找不到模块？ ​

• 问题描述：Lua 报告找不到 lsnmp_core 或无法加载共享库。
• 一句话答案：检查 lsnmp.so 是否安装在 Lua C 模块搜索路径中，以及其动态依赖是否完整。
• 根因说明：模块入口名是 luaopen_lsnmp_core，文件由构建系统安装到 /opt/bmc/luaclib/lsnmp.so；路径、文件或依赖缺失都会导致加载失败。
• 解决方案：确认文件存在，将 /opt/bmc/luaclib/?.so 纳入 package.cpath，并根据加载器报错补齐依赖。
• 规避方案：通过组件包和正式构建流程安装，不要只复制单个共享库。
• 适用版本：1.30.16。

Q2：为什么 send_snmp_trap_msg 返回 -1 并提示版本错误？ ​

• 问题描述：日志出现 get snmp version failed 或 the version name is invalid。
• 一句话答案：version 必须精确填写为 SNMPv1、SNMPv2c 或 SNMPv3。
• 根因说明：组件对版本字符串做区分大小写的精确匹配。
• 解决方案：修正 SNMP_TRAP_MSG.version 后重试。
• 规避方案：在上层使用固定枚举映射，不接受任意版本字符串透传。
• 适用版本：1.30.16。

Q3：为什么 SNMPv3 Trap 初始化失败？ ​

• 问题描述：日志出现 set_snmpv3_key failed、set_snmpv3_engine failed 或 init snmp session failed。
• 一句话答案：核对用户名、算法、本地化密钥以及 snmpd 配置文件中的 EngineID。
• 根因说明：SNMPv3 会话固定使用 authPriv，必须同时配置鉴权和加密信息；组件还会从配置文件读取 oldEngineID 或 oldEngineBakID。
• 解决方案：提供合法十六进制密钥、匹配的算法和可读配置文件，并确认 EngineID 与密钥本地化时一致。
• 规避方案：统一通过 generate_ku/generate_kul 生成密钥，并在配置变更后重新本地化。
• 适用版本：1.30.16。

Q4：为什么 generate_ku 失败或每次结果不一致？ ​

• 问题描述：抛出 runtime_error，或口令较短时结果异常。
• 一句话答案：使用不少于 8 字符的口令，并选择有效鉴权协议。
• 根因说明：当前实现对短口令把传给 net-snmp 的长度提升到 8，可能读取超出口令实际内容的数据，结果不可预期。
• 解决方案：使用长度至少为 8 的口令重新生成 Ku；同时确认协议枚举一致。
• 规避方案：上层在调用前强制校验口令长度。
• 适用版本：1.30.16。

Q5：为什么 API 返回 0，管理站仍收不到 Trap？ ​

• 问题描述：调用成功但管理站没有事件。
• 一句话答案：返回 0 只表示报文已成功提交给本机 net-snmp/UDP 发送路径，不代表远端确认接收。
• 根因说明：Trap 使用 UDP，没有应用层确认；路由、防火墙、目的端口、团体名、SNMPv3 凭据或管理站过滤规则都可能丢弃报文。
• 解决方案：两端抓包确认报文路径，再核对版本、端口、团体名或 SNMPv3 用户/算法/密钥。
• 规避方案：部署前进行端到端测试 Trap 验证，并监控网络策略变化。
• 适用版本：1.30.16。

附录 ​

附录 A 参考资料 ​

• Net-SNMP 官方网站
• Mulan PSL v2

附录 B 修订记录 ​