SNMP Trap Endpoint v0.37.0+ Listens on UDP port 162 and passively receives SNMP Trap/Inform alerts proactively pushed by network/facility devices (switches/routers/UPS/sensors, etc.), converting them into messages that flow into a rule chain. No polling is required, which makes it ideal for device alarm scenarios (such as link-down events, UPS low-battery, temperature thresholds, etc.). It complements the active collection component x/snmpRead.

TIP

1. This is an extension component and requires the additional library: rulego-components-iot (opens new window)

Type

endpoint/snmp

Configuration

Field	Type	Description	Default
server	string	Listen address (including port), e.g. 0.0.0.0:162	0.0.0.0:162
version	string	SNMP version (used to decode Traps), options: v1/v2c/v3	v2c
community	string	Community string (used to validate v1/v2c Traps)	public

WARNING

Port 162 is a privileged port (<1024).

• Linux: run as root, or grant the process the capability to bind privileged ports: sudo setcap cap_net_bind_service=+ep ./your_app.
• Windows: typically run as Administrator. If granting privileges is inconvenient, listen on a non-privileged port (e.g. 0.0.0.0:1162), but adjust the Trap destination port configured on the device accordingly.

Received Message Format

On each Trap received, the component converts it into a RuleMsg flowing into the rule chain, with msg.type = SNMP_TRAP, dataType = JSON, and msg.Data as the following JSON string:

{
  "from": "192.168.1.10:54321",
  "version": "v2c",
  "community": "public",
  "timestamp": 12345,
  "variables": [
    { "oid": "1.3.6.1.6.3.1.1.4.1.0", "value": "1.3.6.1.6.3.1.1.5.1", "type": "ObjectIdentifier" },
    { "oid": "1.3.6.1.2.1.2.2.1.1.1", "value": 1, "type": "Integer" }
  ]
}

Field	Type	Description
from	string	Address of the device that sent the Trap (host:port)
version	string	SNMP version string: v1/v2c/v3
community	string	Community string
timestamp	number	Trap timestamp (from gosnmp SnmpPacket.Timestamp; unit is protocol-defined, typically hundredths of a second)
variables	array	List of PDU variable bindings carried by the Trap; each element contains oid/value/type

Each element of variables:

Field	Type	Description
oid	string	Variable OID
value	any	Variable value
type	string	SNMP type string: Integer/OctetString/ObjectIdentifier/IPAddress/Counter32/Gauge32/TimeTicks/Counter64/Null/Unknown

Among these, 1.3.6.1.6.3.1.1.4.1.0 (snmpTrapOID) identifies the specific alarm type of the Trap and can be used to route dispatching within the rule chain.

Metadata

On each Trap received, the component also writes the following key fields into msg.Metadata, so downstream nodes can read them via ${metadata.xx} directly (especially handy for filter/switch nodes to dispatch by these fields):

key	Description
from	Address of the device that sent the Trap (host:port)
community	Community string
version	SNMP version: v1/v2c/v3
trapOID	Trap alarm type OID (the value of snmpTrapOID 1.3.6.1.6.3.1.1.4.1.0 in variables; v2c/v3 only)

Example: dispatch by alarm type with a filter node — condition metadata.trapOID == '1.3.6.1.6.3.1.1.5.1' routes to the "link down" branch.

The full Trap data (including all variables) remains in msg.Data; metadata only extracts common key fields for routing convenience.

Features

• Passive listening: does not proactively request devices; only receives Traps that devices actively report on exceptions/state changes — high real-time responsiveness with low traffic overhead.
• Complementary to active collection: use this endpoint for alarm events; for periodic metric collection use x/snmpRead triggered by an endpoint/schedule endpoint.
• Graceful shutdown: supports graceful shutdown — in-flight Traps are allowed to complete when stopping.

Example

The following rule chain defines an endpoint/snmp in metadata.endpoints that listens on 0.0.0.0:162 and routes received Traps to a log node:

{
  "ruleChain": {
    "name": "snmp trap demo",
    "root": true
  },
  "metadata": {
    "endpoints": [
      {
        "id": "node_1",
        "type": "endpoint/snmp",
        "name": "SNMP Trap Listener",
        "configuration": {
          "server": "0.0.0.0:162",
          "version": "v2c",
          "community": "public"
        },
        "routers": [
          {
            "id": "router_1",
            "from": {
              "path": "/"
            },
            "to": {
              "path": "node_2"
            }
          }
        ]
      }
    ],
    "nodes": [
      {
        "id": "node_2",
        "type": "log",
        "name": "print trap",
        "configuration": {
          "jsScript": "return 'SNMP Trap received:\\n' + JSON.stringify(msg);"
        }
      }
    ]
  }
}