SNMP Agent
SNMP Agent 将转发组变量映射为数值 OID，供网络管理平台执行 GET、GETNEXT、GETBULK 和受控 SET。支持 v1、v2c 及 v3 USM；每个目标明确选择一个协议版本，不自动降级。
公共转发配置见数据转发。需要采集外部 Agent 或接收其 Trap / Inform 时，选择 SNMP Manager。本目标不主动发送 Trap / Inform。
建立 Agent
- 进入“开发配置 → 数据转发”，设置转发组的变量范围，确认源变量在线且已初始化。
- 新增目标，选择“SNMP Agent”，通道类型选择 UDP，设置本地绑定地址，例如
0.0.0.0:161。 - 明确选择
V1、V2c或V3，按对应认证方式填写参数。初次验证时保持“允许写入”为否。 - 在“目标变量属性”中填写完整数值 OID 和 SNMP 语法；标量通常以
.0结尾，表对象应包含实际索引。 - 保存并启用目标，进入“调试 → 操作 → 映射点表”核对 OID、协议类型、值和访问权限。
只有组内变量才会发布。重复 OID 会使建模失败；未配置 OID 的变量计入未映射数量。Agent 提供配置的 OID 表，不自动生成系统 MIB 或解析 MIB 文件。
目标参数
| 参数 | 说明 |
|---|---|
| 本地绑定地址 | 默认 0.0.0.0:161，只使用 UDP。非特权测试可选择 1161 等端口；监听端口应独占。 |
| SNMP 版本 | 默认 V2c。v1 不支持 GETBULK 和 Counter64。 |
| 只读 Community | 默认 public，v1/v2c 必填；最多 255 个可打印 ASCII 字符。 |
| 读写 Community | 默认空值，表示禁止 community SET；非空时该身份也允许读取。 |
| 允许写入 | 默认否。还需变量级允许写入和源变量 RPC 能力。 |
| 最大 varbind 数 | 默认 256，范围 1～512，限制查询及 Bulk 结果数量。一次 SET 最多 32 项且不能重复 OID。 |
| 最大数据报字节数 | 默认 65507，范围 64～65507；v3 至少 484。响应还受主站声明的容量限制。 |
| 请求超时毫秒 | 默认 5000，范围 100～120000，包含业务回写等待。 |
v1/v2c 的 community 在 UDP 报文中明文传输，应在受控网络使用。公共 SSL 字段不用于 SNMP，请保持关闭；需要认证和加密时选用 v3 AuthPriv。
保存时会校验版本、认证组合及报文预算；导入配置在启动前也会执行同样校验。v3 数据报预算不足 484 字节或安全参数不一致时，应先修正配置再启动。
SNMPv3 安全参数
| 参数 | 说明 |
|---|---|
| 权威引擎 ID | 必填，5～32 字节十六进制，即 10～64 个十六进制字符，必须为此 Agent 唯一。 |
| USM 用户名 | 默认 gateway，与主站配置一致。 |
| USM 安全级别 | NoAuthNoPriv、AuthNoPriv、AuthPriv，不接受低于所选级别的普通业务请求。 |
| USM 认证算法 | 认证模式选择 Md5 或 Sha1，并填写至少 8 字符的认证口令；无认证模式选择 None。 |
| USM 私密算法 | AuthPriv 使用 Aes128 并填写至少 8 字符的私密口令；其他级别选择 None。 |
| USM contextName | 默认空字符串，须与管理端一致，最多 32 字符。 |
Agent 会持久化权威引擎启动计数，以支持重启后的时间同步和重放检查。应保留后端数据目录的引擎状态文件及写权限，不应在沿用同一引擎 ID 时删除或回退计数。更换身份时，先停止目标、备份并归档旧身份的状态文件，再配置全新的唯一引擎 ID，使其建立新身份的状态文件，并同步管理平台配置；仅修改 ID 而沿用旧身份文件会被拒绝。
变量参数与值类型
| 参数 | 说明 |
|---|---|
| 对象标识 OID | 完整数值形式，例如 1.3.6.1.4.1.55555.1.0，最多 1024 字符。示例私有子树仅用于测试，生产应使用自己的 MIB 分配。 |
| SNMP 语法 | 选择 Integer、OctetString、ObjectIdentifier、IpAddress、Counter32、Gauge32、TimeTicks、Opaque 或 Counter64；实际源值必须满足语法及数值范围。 |
| 八位组使用文本 | 默认是，仅影响 OctetString。开启时源字符串按 UTF-8 编码；关闭时源字符串应为 Base64。 |
| 允许变量写入 | 默认否；与目标级允许写入共同生效。 |
Integer 为有符号 32 位整数；Counter32、Gauge32、TimeTicks 为无符号 32 位整数；Counter64 为无符号 64 位整数；IpAddress 使用 IPv4 文本。ObjectIdentifier 使用数值 OID 字符串，Opaque 使用 Base64。不要把 UTF-8 文本直接填入要求 Base64 的字段。
v1 不发布 Counter64 对象：GET 返回 noSuchName，遍历跳过该对象；使用 v1 合法语法向该 OID 写入也返回 noSuchName，整批不提交。包含 Counter64 编码的 v1 报文无效，会被丢弃；TGateway 主站会在发送前拒绝此类写入。需要 Counter64 时选择 v2c 或 v3。
查询与受控 SET
- 在映射点表中点击该行“网络探测”。
- 点击“网络读取”，使用当前目标认证参数经真实 UDP 读取对应 OID。
- 需要写入时，在安全测试点开启目标和变量写权限，并确认源变量本身允许 RPC。
- 输入与协议语法一致的 JSON 值，点击“网络写入并读回”，确认后检查结果及源变量。
- 调试中的 OctetString / Opaque 使用线路值的 Base64 表示；OctetString 文本模式会在变量边界执行 UTF-8 转换。
- 使用外部 Manager 验证 GETNEXT / GETBULK；OID 按数字段排序，越过末尾时 v2c/v3 返回 EndOfMibView。
批量 SET 会先检查整批 OID、权限和类型，然后逐项调用源变量 RPC；提交失败后尝试逆序恢复旧值。不同物理设备间无法提供数据库事务级原子性，应使用适合回滚的点；回滚失败会明确返回 undoFailed，需要现场核对。
SET 提交前还会检查完整成功应答能否装入双方报文预算。容量不足时返回 tooBig，不会调用任何源变量 RPC；请求能发送成功，并不表示主站声明的接收容量足够。查询响应超限也返回 tooBig：v1 保留请求的变量绑定，v2c/v3 返回空绑定，错误索引均为 0。v2c/v3 的 GETBULK 在非重复项和重复次数都为 0 时返回空成功结果。
community、USM 用户名和 contextName 使用配置要求的可打印 ASCII，并按实际字节精确匹配。? 是普通字符，不是通配符。身份不符或编码非法的请求会被丢弃，不读取业务值、不调用源回写；发送端修正身份后，合法查询和 SET 可继续执行。
排障
| 现象 | 处理方法 |
|---|---|
| 请求超时 | 检查版本、UDP 地址、端口、community / USM；认证不匹配的报文不会读取业务变量。 |
| v3 重启后失败 | 检查引擎 ID 是否改变、状态文件是否可写或被回退，随后让 Manager 重新发现和同步。 |
| noSuchObject / 遍历不到点 | 检查完整 OID、标量 .0、索引和组范围。 |
| wrongType / wrongValue | 核对 SNMP 语法、JSON 类型、整数范围及八位组编码方式。 |
| notWritable / 业务回写失败 | 检查读写 community、目标及变量双层权限、源变量 RPC 和设备状态。 |
| tooBig | 减少查询 OID 数或 Bulk repetitions，核对双方报文预算；单点仍超限时缩小八位组值或提高双方容量。SET 因此被拒绝时，源值不变。 |
| 引擎状态损坏或身份不匹配 | 停止目标，按计划分配新引擎身份并同步管理端；不要通过反复删除计数文件维持旧身份。 |