x/snmpRead component: v0.37.0+ Reads OIDs in batch from network/facility devices (switches/routers/UPS/sensors, etc.) over the SNMP protocol (v1/v2c/v3).

Additional extension library required: rulego-components-iot (opens new window)

Configuration

Field	Type	Description	Default
server	string	Device address (host or host:port, default port 161)	127.0.0.1:161
version	string	SNMP version, options: v1/v2c/v3	v2c
community	string	Community string (used by v1/v2c)	public
timeout	int	Request timeout in seconds	5
v3 Security		The following fields are used only when version=v3 (SNMPv3 USM security model)
securityLevel	string	Security level, options: noAuthNoPriv/authNoPriv/authPriv	noAuthNoPriv
username	string	v3 user name	None
authProtocol	string	Authentication protocol, options: None/MD5/SHA/SHA224/SHA256/SHA384/SHA512	None
authPassword	string	Authentication password	None
privProtocol	string	Privacy (encryption) protocol, options: None/DES/AES/AES192/AES256	None
privPassword	string	Privacy password	None
points		Default point table
points	[]Point	Default point list to collect; when msg.Data carries valid points, msg.Data takes precedence	None

Point Fields

Fields of each Point (the read node uses only name/addr):

Field	Type	Description	Default
name	string	Point name, used to identify the result	None
addr	string	SNMP OID, e.g. 1.3.6.1.2.1.1.5.0; prefix with walk: (case-insensitive, e.g. walk:1.3.6.1.2.1.2.2.1.10) to traverse the subtree, may return multiple records; without the prefix performs a Get	None
scale	float	Optional scale multiplier; conversion formula eng = raw*scale + offset	1
offset	float	Optional offset	0

All fields support ${msg.xx} / ${metadata.xx} template variables. The type/value fields are write-node only and unused by the read node.

Output

Read results (the unified Data list) are written back to msg.Data with dataType set to JSON. Format:

[
  {
    "name": "sysName",
    "address": "1.3.6.1.2.1.1.5.0",
    "value": "router-01",
    "type": "OctetString",
    "quality": "good",
    "timestamp": "2026-07-23T10:00:00.123Z"
  }
]

Field	Type	Description
name	string	Point name (from configuration)
address	string	The actual returned OID (when addr has a walk: prefix, the specific node under the subtree)
value	any	Value, type determined by the SNMP PDU type
type	string	SNMP type string: Integer/OctetString/ObjectIdentifier/IPAddress/Counter32/Gauge32/TimeTicks/Counter64/Null
quality	string	Data quality: good (success) / bad (failure)
timestamp	string	Collection timestamp (RFC3339 format)

A point with a walk: prefix may return multiple records; a single point failure does not affect others (marked quality=bad). Only when all points fail (a likely connection-level error) does the node reconnect and retry.

Features

• Scheduled collection: use an endpoint/schedule endpoint as a predecessor trigger, with OIDs configured in points.
• Template variables: point fields (addr, etc.) support ${msg.xx} / ${metadata.xx} placeholders.
• Dynamic points: when msg.Data carries a valid point list (JSON array), it takes precedence — handy when points must be decided at runtime.
• Same-chain connection pool: enables ref:// in-chain connection reuse; other nodes in the chain can borrow the connection by node ID to avoid reconnecting. See Component Connection Reuse.
• Auto reconnect & retry: on connection-level failure (all OIDs fail) the node reconnects and retries up to 3 times (maxRetries=3).
• SNMPv3 USM: fully supports the v3 User Security Model (authentication + encryption).

Relation Type

• Success: On success, the message is sent to the Success chain.
• Failure: On failure, the message is sent to the Failure chain.

Example

{
  "ruleChain": {
    "name": "snmp read demo",
    "root": true
  },
  "metadata": {
    "nodes": [
      {
        "type": "x/snmpRead",
        "name": "read device info",
        "configuration": {
          "server": "192.168.1.1:161",
          "version": "v2c",
          "community": "public",
          "timeout": 5,
          "points": [
            { "name": "sysName", "addr": "1.3.6.1.2.1.1.5.0" },
            { "name": "ifInOctets", "addr": "walk:1.3.6.1.2.1.2.2.1.10" }
          ]
        }
      }
    ]
  }
}

SNMPv3 example configuration fragment:

{
  "server": "192.168.1.1:161",
  "version": "v3",
  "timeout": 5,
  "securityLevel": "authPriv",
  "username": "admin",
  "authProtocol": "SHA",
  "authPassword": "authPass",
  "privProtocol": "AES",
  "privPassword": "privPass",
  "points": [
    { "name": "sysUpTime", "addr": "1.3.6.1.2.1.1.3.0" }
  ]
}