SNMP

响应 SNMP v1、v2c 或 v3 的网络设备（UPS、PDU、交换机、路由器、精密空调和环境传感器），在每个点位的轮询间隔通过其代理读取：“SNMP 代理”卡片、用数字或标准名称书写的点位 OID、每个对象读取成的数据类型、读取与写入、发现代理对象的遍历，以及两个完整示例。

SNMP 驱动通过机房设备的 SNMP 代理读写这些设备：UPS、PDU、交换机、路由器、精密空调，以及温度或湿度传感器。它补全了读取服务器管理控制器的 Redfish 驱动：两者合起来覆盖整个机房。每个点位按 OID 读取代理的一个对象，例如 upsBatteryStatus.0 或 ifHCInOctets.2，它的值和其他任何点位的值一样送达各处：Logic、仪表画面，以及 Process 测试台的运行记录。

由工作站发问：每个点位按其轮询间隔，用 SNMPv1、SNMPv2c 或 SNMPv3 读取；“设备”卡片的轮询间隔（ms）与任何驱动一样起作用，每个点位都可以覆盖它。设备主动发送的内容，即它的 trap，不会被接收；见值得了解的限制。

本驱动的一台设备就是一个代理，通过其主机的 UDP 端口 161 访问。设备位于驱动之下，可以归入文件夹，与任何没有串行线路也没有 MQTT 代理的驱动一样，形成 驱动 → 文件夹 → 设备 → 点位。

驱动页面

对有“配置 Connector”权限的角色，页面上有本驱动自己的扫描范围卡片，里面是设备发现要遍历的代理和子树（见设备发现）。它下面是任何驱动都有的设备表（见设备表），用标题右侧的添加设备增加；为空时显示“还没有设备。”驱动的命令栏上有发现设备，在扫描范围卡片填写完整之前呈灰色。

设备

连接

新设备没有主机：显示“尚未填写主机”，在有主机之前不发送任何内容。标题栏显示的 Base URI 就是运行时地址，含版本、当前的 SNMPv3 安全设置、响应超时和重试次数：snmp://192.168.10.40:161?version=2c&timeoutMs=2000&retries=1，或 snmp://192.168.10.2:161?version=3&security=authPriv&auth=sha256&priv=aes128&timeoutMs=2000&retries=1。它从不包含 community、用户或任何密码。

“SNMP 代理”卡片

在“连接”卡片下面，SNMP 代理卡片说明如何询问代理。它绘制的字段取决于版本，在 SNMPv3 下还取决于安全级别。

两个密码下面写着：“每个密码都是代理为该用户保存的密码，至少 8 个字符。”用户、安全级别和两个协议，都是代理在设备自身的设置页面上为该用户配置的内容：工作站无法向代理询问它们。之所以提供 MD5、SHA-1 和 DES，是因为许多已安装的设备不接受更新的算法。

尚未填写的凭据不算错误：设备照常保存，在凭据填写之前驱动不向代理发送任何内容，卡片下面平静的一行说明还缺什么，取以下第一条：

有主机但仍缺凭据的设备不会连接，它的最近错误会说出代理在等哪一项凭据。卡片不能接受的值不会保存，卡片用红色说明原因：

保存时遵守和卡片相同的规则，拒绝时操作记录条会这样说：“设备‘UPS room 1’有驱动无法使用的 SNMP 设置。请打开它并修正面板标出的字段。”community 和两个密码与任何设备凭据一样保管（见凭据与证书）：为输入它们的 Windows 账户加密存储，在配置导出中密封，从不显示在 Base URI、诊断日志或代理的回答中。在另一个 Windows 账户下输入的凭据读出来为空，设备会像从未填写过一样等待它。

点位寻址

OID

本驱动的点位读取其代理的一个对象。点位的“信号源”卡片上有 OID 框，下面的提示是“用数字写的 OID（例如 1.3.6.1.2.1.1.3.0），或带实例的标准名称（例如 sysUpTime.0、ifInOctets.2、upsBatteryStatus.0）”。无论点位用哪种形式书写，请求携带的都是数字：

框下面以只读方式显示两种形式的 OID：

没有标准名称的对象会多出一行：“设备自有 MIB 中的对象：由于不读取 MIB 文件，按其数字显示。”驱动无法读取其 OID 的点位不会保存，点位页面会说明原因：

保存时遵守同样的规则：“点位‘Battery status’未指向 SNMP 驱动能读取的 OID。请打开它并修正点位面板标出的地址。”只读的源地址（总线）一行显示驱动收到的数字：写作 upsBatteryStatus.0 的点位为 1.3.6.1.2.1.33.1.2.1.0。

驱动认识的名称

驱动带有一张值得命名的标准 MIB 对象表，依据 RFC 编写，因此一个名称在每个工作站上都表示同一个东西。不读取任何 MIB 文件。

driver_capabilities 列出每个名称及其 OID；见智能体工具。

数据类型与访问

数据类型列表只提供对象能无损读取的类型：

计数器不提供 Float，因为 Float 超过 16,777,216 会舍入；Counter64 不提供 Int64，因为 Int64 会拒绝超过其一半的计数。从不提供 Boolean：SNMP 没有布尔值，它的 TruthValue（1 为真，2 为假）与设备自定的 0 和 1 会把同一类型读成相反的两种意思，所以状态按 Int32 读取。OID 改变时，新对象无法读取的类型会变成它最自然的读取类型；而它无法读取的类型会被拒绝，并列出它可以读取的类型：“ifHCOutOctets.2 可按以下类型之一读取：UInt64, Double, String。”

MIB 声明为只读的标准对象（计数器、sysUpTime、各种状态）只提供只读，“访问”字段下写着“只读：这个值由设备报告，外部不能设定它。”MIB 声明为可写的标准对象（sysContact、sysName、sysLocation、ifAdminStatus、ifAlias、UPS-MIB 的测试、控制和配置对象）以及设备自有 MIB 中的对象提供全部访问方式：代理是否接受写入，由它自己回答。

读取

在每个点位的轮询间隔，工作站发送一个 GET。代理的应答决定点位显示什么（见数值转换链）：

一台设备一次只发一个请求。一次读取询问该点位的对象，并在同一个请求中询问设备上其他没有新鲜应答的点位，最多 32 个 OID；代理回答请求太大（tooBig）时，此后只发一半。这样带回的应答，在比另一个点位轮询间隔的一半更新时，用于该点位自己的读取，所以四十个点位每一轮只需一两个请求。SNMPv3 代理的引擎每次连接学习一次；代理报告超出其时间窗口的请求，会按代理自己的数值再发送一次。

写入

访问方式为写的点位通过设备的队列发送 SET。写入与其他任何驱动走同一条通道：写入框接收工程值，在发送原始值之前把转换环节反向执行（见 Connector）。SET 携带的值类型依次取：代理上次应答该对象时所用的类型；没有时取 MIB 声明的类型；再没有时取此刻 GET 应答的类型；最后取点位自己的类型（Int32 用 Integer32，UInt32 用 Gauge32，String 用 OCTET STRING）。该类型容纳不了的值，在发送任何内容之前就被拒绝。

设备发现

“扫描范围”卡片

对有“配置 Connector”权限的角色，驱动页面上有它的扫描范围卡片，标题下一行写着“遍历一个代理的标准子树并列出找到的内容。SNMPv3 代理需通过其设备扫描：请将该设备选为要扫描的代理。”

范围还缺什么，会以红色写在卡片下面，在填写完整之前发现设备保持灰色：

要扫描的设备有无法保存的编辑时，扫描不会开始：“设备发现没有开始，因为要扫描的设备的修改无法保存。”

扫描提供的内容

发现设备先询问代理的名称（sysName.0），这也证明代理会响应这些凭据；然后遍历每个勾选的子树和指定的子树，SNMPv2c 和 SNMPv3 用 GETBULK，SNMPv1 用 GETNEXT，直到代理应答到子树之外。进度行计数已读取的内容：“正在遍历 192.168.10.40:161 处的 SNMP 代理：找到 120 个对象。”一次扫描最多列出 2000 个对象、最多遍历 60 秒；在此被截断，或代理中途沉默时，它保留已找到的内容并说明：“对 192.168.10.40:161 的遍历提前停止，找到 2000 个对象。一次扫描最多列出 2000 个对象、最多遍历 60 秒，并在代理不再应答时停止。”

扫描为每个代理提供一个候选项，以其 sysName 命名（代理不给名称时用设备名称或主机），带有读取时使用的版本、超时和重试次数，并把找到的对象作为候选点位：

任何点位类型都容纳不了的值会被略去。从输入地址的扫描中添加的设备，保留扫描所用的 community，像任何设备凭据一样加密保存；从设备扫描中添加的设备，带上该设备的凭据。本驱动已有设备在读取其代理的候选项（被扫描的设备，或同一主机和端口上的另一台设备）标记为已经配置过：它的卡片只列出该设备还没有点位读取的对象（按名称写和按数字写的 OID 算作同一个），打开之前的添加所选点位把勾选的对象添加到该设备。扫描的其他行为见设备发现。

设备自己的页面不经过驱动页面也能做同样的事：“点位”卡片标题栏里的发现点位用这台设备的设置和凭据遍历它的代理，范围是标准子树和它的点位已经在读的厂商分支（有点位在 enterprises.318 之下时就是它），只列出它还没有点位的对象（见发现一台设备的点位）。

示例：通过 SNMPv2c 读取 UPS

一台带网卡的 UPS 在 192.168.10.40 上以 SNMPv2c 应答，网卡上设置了只读 community。读取它的电池：

1. 在驱动页面点添加设备；命名为 UPS room 1，在主机填写 192.168.10.40，端口保持 161。
2. 在 SNMP 代理卡片上保持 SNMPv2c，在 Community 填写网卡的只读 community，响应超时（ms）保持 2000，重试次数保持 1。要求填写 community 的那一行随即消失。
3. 添加点位 Battery status，OID upsBatteryStatus.0，数据类型 Int32。框下面的 MIB 名称显示 upsBatteryStatus.0 和 UPS-MIB · Integer32 · 只读，数字 OID 为 1.3.6.1.2.1.33.1.2.1.0，访问保持只读。值为 1 unknown、2 batteryNormal、3 batteryLow 或 4 batteryDepleted。
4. 添加点位 Battery charge，OID upsEstimatedChargeRemaining.0，数据类型 Int32，单位 %。
5. 如果 UPS 提供，添加点位 Minutes remaining，OID upsEstimatedMinutesRemaining.0，数据类型 Int32，单位 min。

Base URI 为 snmp://192.168.10.40:161?version=2c&timeoutMs=2000&retries=1。智能体用工具做同样的事：

device_upsert name="UPS room 1" driver=Snmp host=192.168.10.40 snmpVersion=V2c snmpCommunity="<the UPS card's read community>"
tag_upsert device="UPS room 1" name="Battery status" address=upsBatteryStatus.0 opcUaType=Int32
tag_upsert device="UPS room 1" name="Battery charge" address=upsEstimatedChargeRemaining.0 opcUaType=Int32 unit=%
tag_upsert device="UPS room 1" name="Minutes remaining" address=upsEstimatedMinutesRemaining.0 opcUaType=Int32 unit=min

示例：通过 SNMPv3 读取交换机的接口计数器

192.168.10.2 上的一台网管交换机为用户 scada 以 SNMPv3 应答，交换机上为它配置了 SHA-256 认证和 AES-128 加密。读取其端口 2 的流量和状态：

1. 添加设备；命名为 Core switch，主机 192.168.10.2，端口 161。
2. 在 SNMP 代理卡片上选择 SNMPv3，在 SNMPv3 用户填写 scada，保持签名并加密（authPriv），在认证协议选择 SHA-256 并填写其密码，加密协议保持 AES-128 并填写其密码：都是交换机为 scada 保存的密码，至少 8 个字符。
3. 添加点位 Port 2 in，OID ifHCInOctets.2。数据类型变为 UInt64，即 64 位计数器的读取类型，列表只提供 UInt64、Double 和 String；单位 B。
4. 添加点位 Port 2 out，OID ifHCOutOctets.2，UInt64，单位 B。
5. 添加点位 Port 2 state，OID ifOperStatus.2，数据类型 Int32：1 up、2 down、3 testing、7 lowerLayerDown。

.2 是交换机上的接口索引，即 ifName.2 所命名的那个接口；扫描接口子树会列出每个接口及其索引。Base URI 为 snmp://192.168.10.2:161?version=3&security=authPriv&auth=sha256&priv=aes128&timeoutMs=2000&retries=1。使用工具时，对象无法读取的 opcUaType（例如 ifHCOutOctets.2 上的 Int32）会被拒绝，并给出它可以读取的类型：

device_upsert name="Core switch" driver=Snmp host=192.168.10.2 snmpVersion=V3 username=scada password="<authentication password>" snmpSecurityLevel=AuthPriv snmpAuthProtocol=Sha256 snmpPrivacyProtocol=Aes128 snmpPrivacyPassword="<privacy password>"
tag_upsert device="Core switch" name="Port 2 in" address=ifHCInOctets.2 opcUaType=UInt64 unit=B
tag_upsert device="Core switch" name="Port 2 out" address=ifHCOutOctets.2 opcUaType=UInt64 unit=B
tag_upsert device="Core switch" name="Port 2 state" address=ifOperStatus.2 opcUaType=Int32

智能体工具

driver_capabilities 在 snmp 下描述本驱动：各版本及其接受的凭据、安全级别和协议、响应超时和重试次数、OID 的写法、按值类型划分的数据类型、驱动认识的每个名称（含 MIB、OID 以及是否可写）、读取与写入的行为、设备发现，以及上面的两个示例。device_upsert driver=Snmp 接受 host、port（默认 161）、snmpVersion（V1、默认的 V2c 或 V3）、SNMPv1 和 SNMPv2c 下的 snmpCommunity（'' 清除它），以及 SNMPv3 下的 username（用户）、password（其认证密码，至少 8 个字符）、snmpSecurityLevel（默认的 AuthPriv、AuthNoPriv 或 NoAuthNoPriv）、snmpAuthProtocol（Md5、默认的 Sha1、Sha256、Sha384 或 Sha512）、snmpPrivacyProtocol（Des、默认的 Aes128、Aes192 或 Aes256）和 snmpPrivacyPassword；另有 responseTimeoutMs（100 到 60000，默认 2000）和 snmpRetries（0 到 5，默认 1）。SNMPv3 设备上的 community，或 community 设备上的 SNMPv3 字段，会被拒绝。工具返回的设备带有 snmp：版本、hasCommunity、当前的安全级别和协议、hasPrivacyPassword、超时、重试次数，以及 missingCredential，即它仍在等待的凭据；从不返回任何秘密。tag_upsert 以 address 接收 OID，opcUaType 默认为对象最自然的读取类型；wireQuantity 和 eipPath 会被拒绝。device_discover driver=Snmp 或者遍历 target（一个主机，不是 161 时加 port），配合 snmpVersion（V1 或 V2c）和 snmpCommunity；或者遍历 snmpDevice，即本驱动一台设备的名称，这是扫描 SNMPv3 代理的唯一方式；snmpSubtrees 选择标准子树（System、Interfaces、Ups、Sensors、HostResources，用逗号分隔），snmpSubtree 再加一个。工具不保留扫描用的 community：根据扫描结果创建的设备在 device_upsert 中重新接收它，已配置设备缺少的点位用 tag_upsert 添加。其他工具见智能体工具。

值得了解的限制

• 发生情况时设备主动发送的 trap 和 inform 不会被接收：每个值都按其轮询间隔读取，所以电量变低的电池要到下一次读取其状态时才会看到。
• 不导入任何 MIB 文件。驱动认识的名称来自它内置的标准 MIB；enterprises 下设备自有 MIB 中的对象按数字书写和显示，其含义请查阅厂商文档。
• 工作站本身不是 SNMP 代理：没有任何东西能通过 SNMP 读取工作站本身。
• 扫描只能通过保存了用户和密码的设备访问 SNMPv3 代理，它不会自行尝试任何 community 或用户。
• 一次扫描最多列出 2000 个对象、最多遍历 60 秒：在大型交换机上，请取消勾选不需要的子树，或指定需要的那个。
• 没有 Boolean 点位：TruthValue 或设备自定的开和关都按 Int32 读取。