Skip to main content

SNMP

Driver: snmp

GEM's generic SNMP driver polls any SNMP-capable device — UPSs, PDUs, network switches, environmental sensors, gateways — on a schedule and writes the values it reads into GEM zones. It speaks SNMP v1, v2c, and v3 (with USM authentication and privacy), and it exposes on-demand get, set, and walk commands for one-off reads, writes, and subtree discovery.

One GEM device represents one SNMP agent (one IP address). Each numeric OID you want to track becomes a zone under that device; GEM polls all of a device's OIDs together and stores each result as its zone's state.

When to use the generic SNMP driver

Some gear that happens to speak SNMP already has a purpose-built GEM driver that maps its values to the right verbs for you — an APC UPS (APC UPS), a CyberPower UPS (CyberPower), a WattBox (WattBox). Prefer those on supported hardware. Reach for the generic snmp driver when the device has no dedicated driver and you know — or can discover — the OIDs you need.

Add the SNMP device​

  1. Go to Open Devices (System > Devices) and add a device.
  2. Set the Driver to snmp.
  3. In Agent IP / Host, enter the agent's IP address or hostname. This is the only required field.
  4. Expand the optional settings to set the SNMP version, credentials, and timing (see the table below). The defaults — v2c, community public, UDP port 161 — match a factory read-only agent.
  5. Save. GEM opens a UDP session to the agent and starts polling on the interval you set.

Device settings​

Every field except Agent IP / Host is optional and lives under the device's optional/advanced attributes. The Attribute key column is the exact name to type if you add or edit the value later in the Attributes editor.

Field (form label)Attribute keyDefaultNotes
Agent IP / Hostip—Required. IP address or hostname of the SNMP agent.
UDP Portport161Standard SNMP port.
SNMP Versionversionv2cv1, v2c, or v3.
Community StringcommunitypublicUsed for v1/v2c. Shown only when the version is not v3.
v3 Usernamev3_username—Required for v3.
v3 Security Levelv3_security_levelnoAuthNoPrivnoAuthNoPriv, authNoPriv, or authPriv.
v3 Auth Protocolv3_auth_protocolSHAMD5, SHA, SHA224, SHA256, SHA384, SHA512. Used at authNoPriv/authPriv.
v3 Auth Keyv3_auth_key—Stored encrypted. Used at authNoPriv/authPriv.
v3 Priv Protocolv3_priv_protocolAESDES, AES, AES256B, AES256R. Used at authPriv.
v3 Priv Keyv3_priv_key—Stored encrypted. Used at authPriv.
Request Timeout (ms)timeout5000How long to wait for a reply before retrying.
Retriesretries1Retry count per request.
Poll Interval (ms)status_interval30000How often all of the device's OIDs are read.

The v3 credential fields appear only when SNMP Version is v3; the Community String field appears for v1/v2c. Editing any connection or credential field rebuilds the SNMP session in place — no full device reload needed. The two key fields are stored encrypted.

SNMP versions and authentication​

  • v1 / v2c — set Community String. Most agents ship with public for read and (where writes are enabled at all) private for write. v2c is the default and is what most monitoring uses.
  • v3, noAuthNoPriv — set only v3 Username; leave the auth and priv fields blank.
  • v3, authNoPriv — set v3 Username, v3 Auth Protocol, and v3 Auth Key.
  • v3, authPriv — set all of the above plus v3 Priv Protocol and v3 Priv Key (authenticated and encrypted).
v3 needs a username

When the version is v3 and v3 Username is blank, GEM cannot build the session, and every poll fails silently until you supply it.

Poll OIDs into zones​

GEM does not create zones automatically. For each value you want to track, add a zone under the SNMP device:

  1. Go to Open Zones (System > Zones) and add a zone. Pick a subsystem that fits the data — the SNMP driver suggests Power or Sensor, but any subsystem works.
  2. Set the zone's Device to your SNMP device.
  3. In the zone Address, enter the numeric OID to read — e.g. 1.3.6.1.2.1.1.3.0 for sysUpTime or 1.3.6.1.2.1.1.5.0 for sysName. A leading dot is accepted and stripped.
  4. Save. On the next poll GEM reads the OID and writes the returned value to the zone's state.

Optional zone attributes​

Add these in the Attributes editor on the zone:

Attribute keyLabelPurpose
value_mapValue MapJSON that translates a raw OID value into a friendly state, e.g. {"1": "on", "2": "off"}. A raw value that isn't a key in the map passes through unchanged.
oid_typeOID Type (for set)The SNMP type used when the set command writes this zone's OID. One of Integer, OctetString (default), Null, ObjectIdentifier, IpAddress, Counter, Gauge, TimeTicks, Opaque, Counter64.

How polling works​

  • All of a device's OID-bound zones are read together on the Poll Interval (status_interval, default 30 s). Reads are batched up to 25 OIDs per request, so a device with many zones still polls in a few round-trips.
  • A returned value is written to a zone only when it changed, so a steady reading doesn't churn the zone's history.
  • If the agent answers, the device and each answering zone show connected; an OID the agent rejects (a per-OID error) marks just that zone disconnected while the rest keep updating. If the whole poll fails (timeout, host unreachable), the device shows disconnected.

Value formatting​

  • Numbers come through as numbers; large 64-bit counters come through as their full string form.
  • Text (OctetString) values return as UTF-8 text when they're printable and as a hex string when they aren't — e.g. a MAC address or a binary blob. Use Value Map to turn either into a friendly label.

Commands​

The driver publishes four commands. Run them from the device's Commands tab, from System > Script Console with gem.command(...), or from a macro:

CommandArgumentsWhat it does
getoidReads a single OID and returns its value.
setoid, value, typeWrites a single OID. If type is omitted it uses the target zone's OID Type (falling back to OctetString). Integer-family types are cast to a number, and a non-numeric value is rejected before anything is sent to the device.
walkoidWalks an OID subtree and returns every value under it — the quickest way to discover what a device exposes.
get_status—Forces an immediate poll of every OID-bound zone on the device instead of waiting for the next interval.

For get, set, and walk you can pass the OID as either oid or address; when the command runs against a bound zone (gem.command({zone: <zone_id>, action: 'get'})), GEM fills the OID in from the zone's Address automatically. Writing requires that the agent's community or v3 user has write access — many agents are read-only by default and will return an access error.

Discovering OIDs

Point walk at a high branch — 1.3.6.1.2.1 for the standard MIB-2 tree, or a vendor's enterprise branch — to dump everything the device publishes, then copy the OIDs you care about into zone Address fields.

Troubleshooting​

SymptomCheck
Every zone reports no valueConfirm the agent allows this GEM server's source IP and that the community string (v1/v2c) or v3 credentials match exactly.
Every poll times outVerify UDP 161 is reachable across any firewall/VLAN and that the IP and port are correct. Raise Request Timeout (ms) for a slow agent.
set returns access deniedThe community or v3 user must have write permission. Most agents are read-only out of the box; enable a write community/user on the device first.
A v3 device never connectsMake sure v3 Username is set and the security level matches the device: blank auth/priv for noAuthNoPriv, an auth key for authNoPriv, auth and priv keys for authPriv.
A text value shows as hexThe value isn't printable UTF-8 (binary or MAC-style data). Map it to a label with Value Map, or read the individual bytes with a more specific OID.