SNMP Integration Guide

Poll and control network gear, UPSs, PDUs and environmental sensors over SNMP v1, v2c or v3.

Protocol

SNMP v1 · v2c · v3 (USM) over UDP

Default port

161

Operations

Get OIDs · Walk Subtree · Set OIDs

Read and write values on any device with an SNMP agent: switches, routers, UPSs, PDUs, environmental sensors and printers. MaestroHub acts as an SNMP manager: it sends requests to the agent and reads the responses. You name the numeric OIDs you need and Get them, Walk a subtree to find more, and Set writable objects. This guide covers connection setup, the three operations, how values and quality are reported, and the matching pipeline nodes.

Overview

The SNMP connector provides:

• SNMP v1, v2c and v3: v1 and v2c authenticate with a community string; v3 uses the User-based Security Model (USM) with authentication and encryption
• Get OIDs: read a list of named numeric OIDs, split into several requests when the list is long
• Walk Subtree: list every OID under a root with GETBULK (v2c and v3) or GETNEXT (v1), stopping at a row limit you set
• Set OIDs: write one or more values, each with an explicit SNMP type, in one all-or-nothing request that is sent once
• Honest quality: an OID the agent does not have is reported with quality: "bad" and the reason, never as a value
• Exact counters: Counter64 values stay exact as unsigned 64-bit integers, so a high-speed interface counter above 2⁵³ is not rounded
• Egress protection: cloud-metadata and loopback destinations are refused unless you allow them

Not in this version

• Traps and informs. MaestroHub never binds a listening port, so it does not receive traps or informs. Poll the agent instead, on a Schedule trigger.
• MIB files. You cannot upload MIBs, and names such as sysUpTime.0 are not resolved. Use numeric OIDs (1.3.6.1.2.1.1.3.0); a Walk shows what an agent offers.
• SNMP over TCP or TLS/DTLS, and MaestroHub acting as an agent.

Connection Configuration

Creating an SNMP Connection

Navigate to Connections → New Connection → SNMP and fill in the form. Functions, Scaling and Health unlock after the connection is saved.

1. Profile Information

Field	Default	Description
Profile Name	-	A descriptive name for this connection profile (required, max 100 characters). Must be unique across all connections.
Description	-	Optional description for this connection
Labels	-	Key-value pairs to categorize and organize the connection (max 10 labels)

2. Agent

Field	Default	Description
Host	-	Agent host name or IP address (required)
Port	161	UDP port of the SNMP agent
SNMP Version	v2c	v1, v2c or v3. Prefer v2c over v1: it has 64-bit counters and bulk reads. Use v3 when the agent supports it: v1 and v2c send the community string in clear text.

3. Security

Which fields apply depends on the version.

Field	Applies to	Default	Description
Community	v1, v2c	-	Required for v1 and v2c. The agent's read community for reads, or its write community when this connection will Set. Many devices ship with public (read) and private (write). Stored as a secret.
Security Level	v3	authPriv	authPriv authenticates and encrypts; authNoPriv authenticates only; noAuthNoPriv does neither
User Name	v3	-	Required for v3. The USM user configured on the agent.
Authentication Protocol	v3 authNoPriv, authPriv	SHA256	SHA (SHA-1), SHA224, SHA256, SHA384, SHA512 or MD5. MD5 is weak: use it only for devices that offer nothing else.
Authentication Password	v3 authNoPriv, authPriv	-	At least 8 characters (RFC 3414). Stored as a secret.
Privacy Protocol	v3 authPriv	AES	AES (AES-128), AES192, AES256, or AES192C / AES256C, the key extension Cisco devices use. DES is weak: use it only for devices that offer nothing else.
Privacy Password	v3 authPriv	-	At least 8 characters (RFC 3414). Stored as a secret.
Context Name	v3	-	Optional. The SNMP context to read from; leave empty for the default context.
Allow Loopback Destinations	all	Off	Permit requests to 127.0.0.0/8 and ::1, such as an agent on the MaestroHub host itself. Off by default.
Allow Cloud-Metadata Destinations	all	Off	Permit requests to 169.254.169.254 (AWS) and metadata.google.internal (GCP). Off by default: these endpoints return cloud credentials without authentication.

Secrets are never shown again after saving. Leave a stored secret as it is to keep it, or clear it to type a new one.

4. Advanced

Field	Default	Description
Response Timeout	5s	How long to wait for the agent's response to one request (100 ms to 1 minute) before resending it (reads) or giving up
Read Retries	1	How many times a Get or Walk request is resent when no response arrives (0-5). A Set is never resent.
Max OIDs per Request	20	How many OIDs one Get or Set request carries (1-128). A longer Get list is read in several requests. Lower it if the agent answers tooBig.
Bulk Max Repetitions	10	v2c and v3 Walk: how many rows each GETBULK request asks for (1-100). 10 is net-snmp's default. Lower it if the agent answers tooBig.

Each function also has its own Timeout that bounds the whole operation, including retries and every request of a long Get or Walk.

Testing the Connection

Click Test Connection at the bottom of the form. The probe asks the agent for sysUpTime.0 (1.3.6.1.2.1.1.3.0), after v3 engine discovery, and reports the latency. Any response counts: an agent whose view hides sysUpTime still answers with noSuchObject, and that proves it is reachable with these credentials. No response, or a v3 agent refusing the credentials, fails the test. Ping on the Health tab uses the same request.

Function Builder

Creating SNMP Functions

After the connection is saved:

1. Open the connection and go to the Functions tab
2. Click New Function and choose Get OIDs, Walk Subtree or Set OIDs
3. Fill the Basic fields (name, description, labels) and the Configuration fields
4. Use Test Function to run it against the live agent before saving

OIDs

Every OID is numeric: 1.3.6.1.2.1.1.3.0, with or without a leading dot. Each arc is a whole number up to 4294967295, an OID has at least two arcs, and it starts with 0, 1 or 2. MIB names (sysUpTime.0, IF-MIB::ifInOctets.1) are refused when you save. To find the OIDs a device offers, run a Walk of its subtree (for example 1.3.6.1.2.1.1 for the system group, or 1.3.6.1.4.1 for vendor objects) and copy the OIDs you need.

Get OIDs (snmp.get)

Read the current value of each OID in a list.

Field	Required	Default	Description
OIDs	Yes	-	One row per OID: a name (unique; it keys the result) and a numeric oid. Up to 1000 rows.
Timeout	No	1m	Bound on this operation

A list longer than Max OIDs per Request is read in several requests. Each OID's result carries its SNMP type, its value and its quality:

SNMP	In the result
Integer	A number
Counter32, Gauge32, TimeTicks, Uinteger32	A number (0 to 4294967295). TimeTicks are hundredths of a second.
Counter64	An exact unsigned 64-bit integer
OctetString	Text when it is printable UTF-8; otherwise hex such as 00:1a:2b:3c:4d:5e with encoding: "hex" (MAC addresses, binary status)
ObjectIdentifier	The OID as text, without a leading dot
IpAddress	Dotted text, such as 10.0.0.7
noSuchObject, noSuchInstance, endOfMibView	No value. error names the exception and quality is bad.

An SNMP v1 agent refuses a whole Get with noSuchName when one OID is missing. MaestroHub then reports that OID as bad with error: "noSuchName" and asks for the rest again without it, as net-snmp's snmpget does.

Walk Subtree (snmp.walk)

List every object under a root OID with its type and value, in OID order.

Field	Required	Default	Description
Root OID	Yes	-	Numeric OID of the subtree, such as 1.3.6.1.2.1.2.2 (the interface table)
Max Rows	No	1000	Stop after this many rows (1-10000). The result's truncated is true when the walk stopped early.
Timeout	No	5m	Bound on this operation

v2c and v3 walk with GETBULK, Bulk Max Repetitions rows per request; v1 walks with GETNEXT, one row per request. When the root names a single instance (1.3.6.1.2.1.1.3.0), the walk returns that instance. If the agent refuses a request (for example tooBig), the walk fails and says why, rather than returning a partial list as if it were complete.

Set OIDs (snmp.set)

Write a value with an explicit SNMP type to each OID in a list.

Field	Required	Default	Description
Values	Yes	-	One row per value: an oid, a type, a value, and an optional name (it keys the result; the OID is used when there is none). Supports ((paramName)) templates in the value.
Timeout	No	1m	Bound on this operation

Type	Value
integer	A whole number from -2147483648 to 2147483647
unsigned32, gauge32	A whole number from 0 to 4294967295 (both are sent as Gauge32/Unsigned32)
counter32	A whole number from 0 to 4294967295
timeticks	Hundredths of a second, 0 to 4294967295
counter64	An unsigned 64-bit number. Give a value above 9007199254740992 as text ("18446744073709551615") so it stays exact.
ipAddress	An IPv4 address, such as 10.0.0.7
objectIdentifier	A numeric OID
octetString	Text
hexString	Bytes as hex: 001a2b, 00:1a:2b, 00 1a 2b or 0x001a2b

How a Set behaves:

• Checked before anything is sent. A missing or malformed OID, an unknown type, a fraction for an integer type, a number out of the type's range, or a malformed address or hex string fails the function and sends nothing.
• All or nothing. The values go out in one request, and the agent applies all of them or none (RFC 3416). A Set with more values than Max OIDs per Request is refused rather than split, because splitting it would break that rule.
• Sent once. If the agent's response does not arrive, the result says the outcome is unknown and MaestroHub does not resend the Set: the agent may already have applied it. Read the object back to check.
• A refusal names the object. The agent's error status (notWritable, wrongType, noAccess, noCreation, wrongValue, …) and the value it points at appear in the error. Nothing was applied.
• The connection must use the agent's write community (v1, v2c) or a v3 user with write access.

Using Parameters

The value of a Set row supports ((parameterName)) placeholders; they appear in the Function Parameters block, where you set each one's type, whether it is required, and a default. For example, OID 1.3.6.1.4.1.318.1.1.4.4.2.1.3.1, type integer, value ((command)) writes the node's command parameter. A filled placeholder is checked against the type before the Set is sent.

Testing Functions

Click Test Function on the function form, enter values for any ((parameters)), and click Execute Test. The dialog shows each OID's type, value and quality, the walk's rows, or the agent's refusal. You do not need to save the function first. Testing a Set function writes to the device.

Pipeline Integration

Each operation has its own node: SNMP Get (connected.snmp.get), SNMP Walk (connected.snmp.walk) and SNMP Set (connected.snmp.set), plus the SNMP Read Group (connected.snmp.readgroup) for several Get functions in one node. To poll an agent, drive the reads from a Schedule trigger.

A Set does not run in a pipeline started by a late (replayed) input, and it is never buffered to send later.

See SNMP Nodes for the node reference.

Common Use Cases

UPS and power monitoring

A Get of the UPS's battery charge, remaining runtime, output load and input voltage (from the UPS-MIB 1.3.6.1.2.1.33 or the vendor subtree) every minute, routed to the Unified Namespace with a Condition node raising an alert when the battery runs on its own.

Switch interface counters

A Get of ifHCInOctets and ifHCOutOctets (1.3.6.1.2.1.31.1.1.1.6.<index> and .10.<index>) for the uplinks. They are Counter64 values and arrive exact, so the difference between two polls gives the traffic even on 10 and 100 Gbit/s links. Use a Walk of 1.3.6.1.2.1.2.2.1.2 (ifDescr) once to find each interface's index.

PDU outlet control

A parameterized Set of a PDU outlet's control OID with type integer and value ((command)) (for example on and off codes from the vendor's MIB), fed from an operator form, with a Condition node checking the outlet number first. Read the outlet's state back with a Get afterwards.

Troubleshooting

Connection Issues

Symptom	Possible cause	Solution
Test Connection times out and says to check the host, port, version and credentials	A wrong v1/v2c community: agents silently drop a request with an unknown community, so it looks exactly like an unreachable agent. Or the wrong version, a wrong port, or a firewall dropping UDP 161.	Check the community on the device, that the agent accepts this version, and that UDP 161 is open from MaestroHub to the device.
Fails at once with "wrong digest"	v3: the authentication password or protocol does not match the agent's user	Check the user's authentication protocol and password on the agent. This is reported as permanent: retrying cannot fix it.
Fails with "unknown username" or "unknown security level"	v3: the user does not exist on the agent, or does not allow the chosen security level	Check the user name and the security level the agent configured for it.
Fails with "decryption error"	v3: the privacy password or protocol does not match	Check the privacy protocol (AES vs AES256, or the Cisco C variants) and password.
Refused with "allowLoopback"	The host resolves to 127.0.0.1 or ::1	Turn on Allow Loopback Destinations if you mean to poll an agent on the MaestroHub host.
Refused with "allowMetadata"	The host is a cloud-metadata endpoint	This is refused on purpose. Turn on Allow Cloud-Metadata Destinations only if that is really the target.

Read / Write Issues

Symptom	Possible cause	Solution
An OID has quality: "bad" and error: "noSuchObject" (or noSuchInstance)	The agent does not have that OID, or the community or user's view hides it	Check the OID with a Walk of its parent. A missing instance often means a wrong index (.0 for scalars).
error: "noSuchName" on a v1 agent	The v1 form of the same: the OID does not exist or is not in the view	As above.
The agent refused the request: tooBig	The response would not fit in one SNMP message	Lower Max OIDs per Request for a Get, or Bulk Max Repetitions for a Walk.
A Walk returns truncated: true	The subtree has more rows than Max Rows	Raise Max Rows, or walk a narrower root.
Set refused with notWritable, noAccess or readOnly	The object is read-only, or the community or user has no write access	Use the write community or a user with write access; check that the object is writable in its MIB.
Set refused with wrongType	The type you chose does not match the object's syntax	Use the type the MIB gives for the object (for example integer for an enumerated value, octetString for DisplayString).
Set fails with "no response to the SET … not resent"	The response was lost or the agent is slow	The agent may have applied the value. Read it back with a Get before trying again.
Unknown(0x…) type	The agent sent a type SNMP does not define	Report the device and OID; the value is not interpreted.