SNMP Config Reference
Below is a comprehensive list of each configuration option on the SNMP driver with its default, a description of its purpose and what effect it will have.
The driver options are set on the Drivers screen. The options a tag uses to read and write an SNMP object are set per tag on the Tags screen, and are listed under Tag properties.
Minimum configuration requirements
These are the fields that need a value before the driver will do anything. Everything else has a working default.
| Field | Needed for | Notes |
|---|---|---|
| Driver Interface Name | All | The name tags refer to in Select Driver Interface. |
| Driver | All | Set to SNMP. |
| IP Address | All | A new driver starts with a placeholder address that reaches nothing. |
| SNMP Version | All | Defaults to v2c. It must be a version the agent has enabled. |
| Read Community | v1 and v2c | Defaults to public. It must match the agent's, or the agent does not answer. |
| User | v3 | The SNMPv3 user configured on the agent, with its Authentication and Privacy settings and passwords. |
| Enable | All | The interface is not active until this is on and the changes are applied. |
| OID | Each tag | Set on the tag, not on the driver. Create tags… fills it for you. |
Driver interface
| Property | Default | Notes |
|---|---|---|
| Driver Interface Name | - | The name used to identify this driver interface. Tags reference it from their Select Driver Interface property. |
| Enable | on | Enable communications. Hidden when Enable by Tag is on. |
| Enable by Tag --> | off | Enable and disable the driver from a Boolean tag instead, named in the field beside it. |
| Good Quality When Disabled | off | On: tags on this driver keep good quality while the driver is disabled, and can be written to. Off: they go to bad quality. |
| Driver | Modbus | Set to SNMP to poll and write network devices - switches, routers, UPS and PDU cards, printers - over SNMP v1, v2c or v3. |
Connection
The Discover device…, Create tags… and MIBs… buttons sit beside IP Address. They are described under Discover device, Create tags and Vendor MIBs.
| Property | Default | Notes |
|---|---|---|
| IP Address | 111.111.111.111 | An IP address or host name reachable from this engine, such as 192.168.1.10. The default is a placeholder: replace it, or fill it with Discover device…. |
| Number of Retries | 3 | How many times a request is re-sent when the agent does not answer within Timeout. When the retries are used up, the tags go to bad quality. |
| Return to Online | 60 Seconds | How often to try the agent again once it has stopped answering. The driver never waits less than 5 seconds. With failover enabled, the attempts alternate between the primary and failover addresses. |
| Port | 161 | The UDP port of the agent. Agents listen on 161 unless reconfigured. |
| SNMP Version | v2c | v1 is for the oldest devices only: it has no 64-bit counters, and one bad OID fails the whole request. v2c is the most common; its community is sent in clear text. v3 adds user-based authentication and optional encryption. |
Communities
Shown when SNMP Version is v1 or v2c. Both fields are masked on screen.
| Property | Default | Notes |
|---|---|---|
| Read Community | public | The community the driver reads with. A wrong community gets no reply at all, so it shows as a timeout rather than as an error. |
| Write Community | blank | The community the driver writes with. Leave blank to write with the read community. A write with a read-only community also gets no reply, so it times out. |
SNMPv3 security
Shown when SNMP Version is v3. The settings must match the user configured on the agent. The passwords are masked on screen.
| Property | Default | Notes |
|---|---|---|
| User | blank | The SNMPv3 security name. |
| Authentication | SHA1 | None, MD5, SHA1, SHA256, SHA384 or SHA512. Must match the agent. None is the noAuthNoPriv security level. MD5 and SHA1 are weak; use SHA256 or above where the agent supports it. |
| Authentication Password | blank | At least 8 characters. Hidden when Authentication is None. |
| Privacy | AES128 | None, DES, AES128, AES192 or AES256. None is the authNoPriv level: requests are authenticated but not encrypted. DES is legacy. Hidden when Authentication is None. |
| Privacy Password | blank | At least 8 characters. Hidden when Authentication or Privacy is None. |
| Context Name | blank | Leave blank unless the agent documents one. |
Requests
| Property | Default | Notes |
|---|---|---|
| Max OIDs per Request | 20 | The most tags read in one GET request. If the agent answers tooBig, the driver halves the batch and keeps the smaller size for the life of the connection, and says so in System Errors - lower this setting to match. |
| Max Repetitions | 10 | Rows asked for in each GETBULK request while browsing the agent. Hidden for v1, which has no GETBULK. |
| Timeout | 3000 Milliseconds | How long to wait for each response before a retry. Embedded agents on printers, UPS and PDU cards can take over a second per request; raise this if tags flicker bad on a slow agent. |
The driver sends one request at a time to its agent, never several at once. A driver with no tags still checks the agent every 30 seconds by reading sysUpTime.0, so the connection state is known before the first tag is added.
Traps
| Property | Default | Notes |
|---|---|---|
| Receive Traps | off | Listen for traps and informs from the device. A trap updates every tag whose OID it carries, and then every tag on the driver is polled again. |
| Trap Port | 162 | The UDP port to listen on. Shown when Receive Traps is on. Drivers that use the same port share one listener. |
Traps are matched to a driver by the sender's address - the driver's IP Address, or its Failover IP Address. The credentials must match as well:
- A v1 or v2c driver accepts v1 and v2c traps that carry its Read Community.
- A v3 driver accepts only v3 traps from its User, at its security level. Set the device's trap version to 3.
Informs are acknowledged for v2c and v3. A trap that is ignored because its credentials do not match is reported once in System Errors, naming the driver and the sender.
The trap port has to be reachable:
- Allow inbound UDP on the trap port in the engine's firewall.
- On Windows, the SNMP Trap service also uses port 162. Stop it, or choose another Trap Port and point the device at that port.
- On Linux, ports below 1024 need elevated rights.
If the port cannot be opened, the driver reports why in System Errors and tries again every 30 seconds.
Failover
| Property | Default | Notes |
|---|---|---|
| Enable Failover | off | Enable fail over to the backup connection when the primary interface fails. |
| Failover IP Address | blank | The address of the backup agent. Shown when Enable Failover is on. It uses the same port, version and credentials as the primary. |
| Monitor Failover State --> | off | Set a Boolean tag to true while the driver is on its failover address and false while it is on its primary, named in the field beside it. Shown when Enable Failover is on. |
When the primary agent stops answering, the driver tries the failover address on the next poll. From then on, while neither answers, it tries again every Return to Online seconds, alternating between the two addresses.
Tag properties
Set on the Tags screen, on the Value parameter and on the alarm limit parameters.
| Property | Default | Notes |
|---|---|---|
| Data Source | - | Set to SNMP. |
| Select Driver Interface | - | The SNMP driver interface the tag reads through. |
| OID | blank | The numeric object identifier to read, such as 1.3.6.1.2.1.1.3.0 (sysUpTime). Scalar objects end in .0; table cells end in the row index. MIB names are not supported. The browse button beside it opens Browse for SNMP OID. |
| Write Type | Auto | The SNMP type used when the value is written. Auto uses the type the agent last returned for the OID, which is right for almost every writable object. The other choices are Integer32, Gauge32, Counter32, Counter64, TimeTicks, OctetString, IpAddress and ObjectIdentifier. Hidden when Read Only is on. |
In a tag CSV file these are the Value - SNMP OID and Value - SNMP Write Type columns.
Discover device
Discover device…, beside IP Address, scans the network for SNMP agents and fills in the driver from the one you pick. The scan only reads: it sends one GET to each address, at most 20 at a time, and changes nothing on the devices.
| Field | Default | Notes |
|---|---|---|
| Subnet, range or address | the driver's subnet | A subnet such as 192.168.1.0/24, a range such as 192.168.1.10-60, or one address. At most 256 addresses. With no address on the driver yet, it starts from the engine's own subnet. |
| SNMP version | v2c / v1 | v2c / v1 tries v2c and then v1 with each community. v3 asks for a user instead. |
| Communities to try (comma-separated, up to 5) | the driver's Read Community | public when the driver has none. |
| User, Auth, Auth password, Privacy, Privacy password | - | Shown for v3. As in SNMPv3 security. |
Scan lists every device that answers, with its Address, Device, Vendor, Version, Up time and number of interfaces (Ifs). A /24 takes about 20 seconds. A device answers only if its SNMP configuration allows the engine's address, so a device missing from the list is often one that is not allowing it.
A device already used by another driver is marked Already configured as …. Selecting a device and clicking Use fills IP Address, sets Port to 161, and sets SNMP Version and the credentials that got the answer. Use is unavailable for a row that carries a note. Click Apply changes to keep the values.
Create tags
Create tags…, beside IP Address, reads the device and offers a set of standard tags for it. It is available once the driver has been added and its changes applied, because the tags are planned from the applied settings.
| Field | Default | Notes |
|---|---|---|
| Tag group | the driver name | The group the tags are created in. An SNMP_ prefix is dropped from the driver name. Letters, digits, _ and . only. |
| Polling rate | 5 | Seconds. The polling rate given to every tag created. |
The tags offered depend on what the device answers:
- Interfaces - one entry per interface, with all, none and only up to select them. For each interface: choose Status, Traffic in, Traffic out and Errors. Traffic uses the 64-bit counters except on v1, which cannot carry them.
- System, CPU (Host), UPS and Printer - each with all and none.
An object marked writable allows a SET in its MIB; the device still has to give the driver's credentials write access. Create N tags imports the selection through the tag CSV import. Tags that already exist are updated, not duplicated.
Browse for an OID
The browse button beside a tag's OID opens Browse for SNMP OID, which walks the agent and lists what it answers. Set the tag's Select Driver Interface first: the browser reads through that driver.
| Field | Default | Notes |
|---|---|---|
| Branch | System (description, uptime, name) | The part of the agent's tree to walk. The choices are System (description, uptime, name), Interfaces, Interfaces — names and 64-bit counters (ifXTable), Host resources (CPU, memory, storage), UPS (battery, input, output), Printer (supplies, page counts), Physical inventory (ENTITY-MIB), Sensors — temperature, voltage, fans (ENTITY-SENSOR-MIB), All standard MIBs (mib-2), Vendor-specific (enterprises — named from imported MIBs) and Custom branch…, which asks for a Branch OID. |
| Up to | 2,000 | The most values to read: 500, 2,000, 5,000 or 20,000. |
The list shows each object's Name, Value, Type and OID, and can be filtered, using * as a wildcard. Selecting a row shows its access, units, enumerated values and description, and the type it will set on the tag. Use this OID fills the tag's OID, and sets its Data Type and Write Type as listed under Data types.
Objects in the standard MIBs are named from the dictionary built into the driver. Vendor objects are named only once their MIB files are imported - see Vendor MIBs.
Vendor MIBs
MIBs…, beside IP Address and in Browse for SNMP OID, opens Vendor MIBs. Vendor MIB files give names to a manufacturer's own objects under the enterprises branch. They are shared by every SNMP driver on the engine.
- Copy the MIB files into the MIBs folder in the engine's configuration file directory. Copy path copies the folder's location. Include the MIBs they import, which are often separate
…-SMIor…-TCfiles. - Click Reload. The table lists each File, the Module it defines, the number of Objects, and any Notes on problems found while reading it.
Nothing is uploaded or downloaded: the engine reads the folder only. An imported MIB only adds names. Where the built-in dictionary already names an OID, the built-in entry is kept.
The standard IETF MIBs are built in: SNMPv2-MIB, IF-MIB, IP-MIB, TCP-MIB, UDP-MIB, HOST-RESOURCES, UPS-MIB, Printer-MIB, ENTITY-MIB, ENTITY-SENSOR-MIB, BRIDGE-MIB, EtherLike-MIB and RFC1213-MIB.
Data types
Choosing an OID in Browse for SNMP OID or Create tags… sets the tag's Data Type from the SNMP type the agent returns:
| SNMP type | Data Type |
|---|---|
| OctetString, IpAddress, ObjectIdentifier | String |
| Integer32 | Integer |
| Counter32, Gauge32, TimeTicks | Long Integer |
| Counter64 | Unsigned Long Integer |
- TimeTicks are hundredths of a second.
- An OctetString is read as text when it is printable, and as colon-separated hex when it is not, such as a MAC address.
- A value that does not fit the tag's Data Type gives the tag bad quality, with the type to use instead in System Errors. Text in a numeric tag needs Data Type String; a Counter64 needs Unsigned Long Integer.
Writes
A write to a tag is sent as an SNMP SET with the Write Community (the Read Community when that is blank) or the v3 User, then read back. The type sent is the tag's Write Type. With Auto, the driver uses the type the agent last returned; if the OID has never been read, it reads it first.
The Write dialog waits for the device's answer. It shows waiting for the device to answer…, then closes when the device accepts the write, or reports The device did not accept the write with the reason and offers Write again. Each write is also recorded in System Errors, as Write - <OID>.
The reasons a device refuses a write:
| Reason given | Meaning |
|---|---|
| the OID is read-only or not writable with these credentials | The object cannot be written, or the credentials have no write access to it. |
| set the tag's SNMP Write Type to the type the agent expects | Auto picked a type the agent does not accept, or the OID has never been read. |
| the value is outside what the agent accepts | The value is outside the object's range or enumeration. |
| a write with a read-only community or v3 user gets no reply; check the write credentials | The write timed out. A device does not answer a write from credentials without write access. |
Communication failures
- When the agent does not answer after Number of Retries, every tag on the driver goes to bad quality. The driver tries again every Return to Online seconds.
- On v2c and v3, an OID the agent does not have makes only that tag bad.
- On v1, an OID the agent does not have fails the whole request. The driver marks that tag bad, sets it aside for 60 seconds, and sends the rest of the batch again.
- An OID that is not a numeric OID makes its tag bad without anything being sent.
While the driver has active problems, the driver screen shows a banner listing them, refreshed every 10 seconds. A rejected write clears when a write to the same OID succeeds; the full history is in System Errors.
Licensing
SNMP is a licensed option, licensed per driver interface. Without a license nothing is sent to the device, the tags go to bad quality, and the License - 001 system error and an alarm reporting SNMP Not Licensed are raised. A license applied while the engine is running starts the driver within a second.
Troubleshooting
| Symptom | Cause |
|---|---|
| Every tag is bad and System Errors reports a timeout | The agent never answers a wrong community or v3 credential, so most failures look like this. Check the community or v3 user, that the device allows the engine's address, and the Port. |
| Tags flicker between good and bad | A slow embedded agent. Raise Timeout. |
| System Errors reports tooBig | The agent cannot return that many values in one response. Lower Max OIDs per Request. |
| One tag is bad, the rest are good | The agent does not have that OID, or it is not numeric. Pick it with Browse for SNMP OID. |
| A tag is bad and System Errors asks for another Data Type | The value does not fit the tag. See Data types. |
| A traffic counter jumps back to zero | A 32-bit counter wraps about every 34 seconds on a gigabit link. Use v2c or v3 and the 64-bit counters. See Create tags. |
| A write times out | The write community or v3 user has no write access. See Writes. |
| A write is rejected | See the reasons under Writes. |
| No traps arrive | The trap port is blocked or in use, or the trap comes from another address or with other credentials. See Traps. |
| Discover device… finds nothing | The device does not allow the engine's address, or the communities are wrong. See Discover device. |
| Create tags… is unavailable | The driver has not been added, or has changes not yet applied. See Create tags. |
| Vendor objects show only as numbers | Their MIB is not imported, or a MIB it imports is missing. See Vendor MIBs. |
| Every tag is bad and System Errors reports SNMP Not Licensed | See Licensing. |
Where next
- SNMP Driver - what the driver does and how it fits together.
- Getting Started with SNMP - these options in a working configuration.
- Device Connectors - the rest of the device connectors.