SNMP Nodes
Read and write SNMP agents on network gear, UPSs, PDUs and sensors from a pipeline: named OIDs, whole subtrees, or a group of reads.
- Needs
- SNMP connection
- Operations
- SNMP Get · SNMP Walk · SNMP Set · SNMP Read Group
- Addressing
- Numeric OIDs (no MIB names)
- Limits
- A Set is sent once, all or nothing
Read and write SNMP agents directly from pipelines. Each operation has its own node in the Pipeline Designer (SNMP Get, SNMP Walk and SNMP Set), plus an SNMP Read Group node that runs several Get functions in one node.
For connection setup, versions and security, OIDs, value types and per-function fields, see the SNMP connection guide.
Configuration Quick Reference
| Field | What you choose | Details |
|---|---|---|
| Parameters | Connection, Function, Function Parameters, Timeout Override | Select the SNMP connection profile, pick a function, bind parameters with expression support, and optionally override the timeout. |
| Settings | Description, Timeout (seconds), Retry on Timeout, Retry on Fail, On Error | Node description, maximum execution time, retry behaviour on timeout or failure, and error strategy. All execution settings default to pipeline-level values. |
SNMP Get Node
Read the current value of a list of named numeric OIDs. Runs an snmp.get function.
Node Configuration
| Parameter | Type | Required | Description |
|---|---|---|---|
| Connection | Selection | Yes | SNMP connection profile to use |
| Function | Selection | Yes | An snmp.get function from the selected connection |
| Function Parameters | Dynamic | Varies | Auto-populated from the function. See Get OIDs. |
| Timeout Override | Number (seconds) | No | Override the default function timeout |
Output Structure
Every OID appears under results by the name you gave it. An OID the agent returned a value for has type, value and quality: "good". An OID the agent does not have has no value: error names the SNMP exception (noSuchObject, noSuchInstance, endOfMibView, or noSuchName on v1) and quality is bad. A value is never invented.
{
"result": {
"results": {
"uptime": { "oid": "1.3.6.1.2.1.1.3.0", "type": "TimeTicks", "value": 4213377, "quality": "good" },
"wanIn": { "oid": "1.3.6.1.2.1.31.1.1.1.6.1", "type": "Counter64", "value": 18446744073709551000, "quality": "good" },
"mac": { "oid": "1.3.6.1.2.1.2.2.1.6.1", "type": "OctetString", "value": "00:1a:2b:3c:4d:5e", "encoding": "hex", "quality": "good" },
"temp": { "oid": "1.3.6.1.4.1.12345.1.0", "type": "NoSuchObject", "error": "noSuchObject", "quality": "bad" }
},
"count": 4,
"quality": "bad"
},
"_metadata": { "success": true, "functionId": "<function-id>", "durationMs": 4, "timestamp": "2026-10-20T08:30:00Z" }
}
| Field | Type | Description |
|---|---|---|
result.results | object | Every OID by its name: oid always; type, value and quality: "good" when the agent returned a value (Counter64 as an exact unsigned 64-bit integer, a non-text OCTET STRING as hex with encoding: "hex"); error naming the SNMP exception and quality: "bad" when it did not |
result.count | number | How many OIDs were read |
result.quality | string | The worst quality of the items: bad when any OID had no value |
{{ $node["SNMP Get"].result.results.uptime.value }}
SNMP Walk Node
List every OID, type and value under a subtree. Runs an snmp.walk function.
Node Configuration
| Parameter | Type | Required | Description |
|---|---|---|---|
| Connection | Selection | Yes | SNMP connection profile to use |
| Function | Selection | Yes | An snmp.walk function from the selected connection |
| Function Parameters | Dynamic | Varies | rootOid, maxRows. See Walk Subtree. |
| Timeout Override | Number (seconds) | No | Override the default function timeout |
Output Structure
{
"result": {
"rootOid": "1.3.6.1.2.1.1",
"rows": [
{ "oid": "1.3.6.1.2.1.1.1.0", "type": "OctetString", "value": "Linux core-sw-01" },
{ "oid": "1.3.6.1.2.1.1.3.0", "type": "TimeTicks", "value": 4213377 }
],
"count": 2,
"truncated": false
},
"_metadata": { "success": true, "functionId": "<function-id>", "durationMs": 12, "timestamp": "2026-10-20T08:30:00Z" }
}
| Field | Type | Description |
|---|---|---|
result.rootOid | string | The subtree that was walked |
result.rows | array | Every object under the root in OID order: oid, type, value, and encoding: "hex" for a non-text OCTET STRING |
result.count | number | How many rows were returned |
result.truncated | boolean | true when the walk stopped at Max Rows before the end of the subtree |
{{ $node["SNMP Walk"].result.rows }}
SNMP Set Node
Write typed values to one or more writable OIDs. Runs an snmp.set function.
The values go out in one request and the agent applies all of them or none. The Set is sent once: if the agent's response does not arrive, the node fails with the outcome unknown and MaestroHub does not resend it, because the agent may already have applied it. It does not run in a pipeline started by a late (replayed) input.
Node Configuration
| Parameter | Type | Required | Description |
|---|---|---|---|
| Connection | Selection | Yes | SNMP connection profile to use |
| Function | Selection | Yes | An snmp.set function from the selected connection |
| Function Parameters | Dynamic | Varies | The values' ((paramName)) placeholders. See Set OIDs. |
| Timeout Override | Number (seconds) | No | Override the default function timeout |
Output Structure
{
"result": {
"results": {
"contact": { "oid": "1.3.6.1.2.1.1.4.0", "type": "octetString", "value": "ops@example.com" }
},
"count": 1
},
"_metadata": { "success": true, "functionId": "<function-id>", "durationMs": 5, "timestamp": "2026-10-20T08:30:00Z" }
}
| Field | Type | Description |
|---|---|---|
result.results | object | Every value written, by its name (or its OID when unnamed): oid, type and the value as given (after parameter substitution) |
result.count | number | How many values were written |
A value its type cannot hold, a malformed OID or more values than Max OIDs per Request fails the node before anything is sent. An agent refusal (notWritable, wrongType, noAccess, …) fails the node with the status and the value it points at; nothing was applied.
Validate values in a Condition node before writing to equipment. A Set can switch a PDU outlet or reconfigure a port immediately.
SNMP Read Group Node
Execute multiple Get functions from a single SNMP connection in one node. The read group runs the selected functions (in parallel or sequentially) and merges their results, which is ideal for polling several groups of OIDs from one agent without a node per function.
The connection carries one request at a time, so parallel functions queue on it rather than overtake each other. Walk and Set functions are never part of a read group.
Supported Function Types:
| Function Name | Purpose |
|---|---|
Get OIDs (snmp.get) | A list of named OIDs per function |
Node Configuration
| Parameter | Type | Required | Description |
|---|---|---|---|
| Connection | Selection | Yes | SNMP connection profile to use |
| Function Selection | Selection | No | Select Functions (default) reads the functions you list, All Functions reads every Get function on the connection, By Labels reads every function whose labels match the labels you pick |
| Functions | List | With Select Functions | One or more Get functions from the selected connection, each with an optional alias that becomes its output key |
| Execution Mode | Selection | No | How to execute the functions (parallel or sequential) |
| Continue on Error | Toggle | No | On by default: a failed read is recorded in the output and the other functions still run. Off: the node fails as soon as any function fails |
Output Structure
The node output is the canonical {result, _metadata} envelope: result holds one entry per function read, keyed by the function's output key; _metadata holds the group's accounting. An snmp.get result has no top-level value, so each entry's value is the function's whole result.
{
"result": {
"Core Switch": {
"value": {
"results": { "uptime": { "oid": "1.3.6.1.2.1.1.3.0", "type": "TimeTicks", "value": 4213377, "quality": "good" } },
"count": 1,
"quality": "good"
},
"success": true,
"error": "",
"duration": 6,
"timestamp": "2026-10-20T08:30:00Z"
}
},
"_metadata": {
"connectionId": "conn-123",
"connectionName": "Core Switch",
"total": 1,
"successful": 1,
"failed": 0,
"totalDuration": 9,
"executionMode": "parallel",
"originalRequests": 1
}
}
{{ $node["SNMP Read Group"].result["Core Switch"].value.results.uptime.value }}
Each entry under result is one function's read, keyed by the function's alias, else its name, else its id:
| Field | Type | Description |
|---|---|---|
result.<alias>.value | any | What the function read: its own result.value when it has one, otherwise its whole result (for snmp.get, the whole {results, count, quality} object). null when the read failed |
result.<alias>.success | boolean | true when this function's read succeeded |
result.<alias>.error | string | Why the read failed; empty when it succeeded; always present |
result.<alias>.duration | number | How long this function's read took, in milliseconds |
result.<alias>.timestamp | string | When the read was issued, RFC 3339 UTC |
The _metadata object is the group's execution summary:
| Field | Type | Description |
|---|---|---|
_metadata.connectionId | string | The connection every function was read on |
_metadata.connectionName | string | That connection's display name |
_metadata.total | number | How many functions the group ran |
_metadata.successful | number | How many read successfully, including the ones onChange then suppressed |
_metadata.failed | number | How many failed; successful + failed = total |
_metadata.totalDuration | number | Wall-clock time of the whole group, in milliseconds |
_metadata.executionMode | string | parallel or sequential |
_metadata.originalRequests | number | How many functions were selected to run |
_metadata.keyCollisions | string[] | Output keys that two or more functions resolved to; the later read overwrote the earlier under that key. Present only when it happened |
_metadata.configWarnings | string[] | Non-fatal problems in the node's config, each saying what was ignored. Present only when there were any |
_metadata.outputMode | string | onChange, present only in that mode |
_metadata.suppressedCount | number | onChange mode: how many successful reads were unchanged since the last run and left out of result |
_metadata.emittedCount | number | onChange mode: how many entries result carries: total − suppressedCount |
_metadata.suppressedKeys | string[] | onChange mode: the output keys left out as unchanged. Present only when at least one was |
_metadata.reason | string | onChange mode, when every successful read was unchanged: why result is empty; the node buffers instead of waking downstream |
Settings Tab
All SNMP node types share the same Settings tab:
| Setting | Type | Default | Description |
|---|---|---|---|
| Description | Text | - | Optional description displayed on the node |
| Timeout (seconds) | Number | Pipeline default | Maximum time the node may run before timing out |
| Retry on Timeout | Toggle | Pipeline default | Automatically retry the node if it times out |
| Retry on Fail | Toggle | Pipeline default | Automatically retry the node if it fails |
| On Error | Selection | Pipeline default | Error strategy: Pipeline Default (the pipeline's Error Handling setting), Stop Pipeline or Continue Execution |
When left at their defaults, these settings inherit from the pipeline-level execution configuration. Retry on Fail on an SNMP Set node can send the Set again after a lost response; that is harmless for a setpoint, but leave it off for a value whose repetition matters.
Use Test Function in the function form (on the connection page) to run every SNMP function against the live agent before wiring it into a pipeline. It catches a wrong OID, a missing write community, or a type the object does not accept.