SNMP
The SNMP driver reads values from SNMP agents: switches, routers, UPSs, printers, environment sensors and other devices with an SNMP interface. It polls them and also receives their traps. For what all drivers have in common, see How drivers work.
Protocol and role
| Role | SNMP manager. YTCC asks the agent for values (GET) and receives its traps. |
| Versions | SNMPv1, SNMPv2c, SNMPv3 (user-based security) |
| Transport | UDP |
| Default ports | 161 for requests to the agent, 162 for traps |
| Devices per driver | One. Add a driver for each agent. |
| Driver type | SNMP (snmp) |
Device parameters
Set these on the device in Drivers → devices (see Add drivers and devices). An empty box uses the default shown in it. The help mark next to each parameter shows a short description.
| Parameter | Default | Meaning |
|---|---|---|
| Host | — (required) | IP address or host name of the agent. |
| Port | 161 | UDP port of the agent, 1–65535. |
| Version | v2c | V1, V2c or V3. |
| Community | public | Community string for v1 and v2c. Also checked on incoming traps. |
| Poll interval (ms) | 2000 | Read period of all signals of the device; at least 50 ms. |
| Timeout (ms) | 2000 | Wait for the answer to one request; at least 50 ms. |
| Retries | 1 | Leave it as it is. A request that is not answered is read again at the next poll. |
| Set invalid on disconnect | on | Leave it on. The signals of an agent that does not answer show Bad · Not connected. |
| Trap enabled | on | Receive traps from this agent. |
| Trap bind | 0.0.0.0:162 | Local address and port for traps. 0.0.0.0 uses all network interfaces. |
| Trap allowed sources | empty | IP addresses that may send traps, or * for any. Empty: only the address of Host. A list does not add Host by itself; put it in the list too. |
| Sec name | empty | SNMPv3 user name. |
| Sec level | authPriv | noAuthNoPriv, authNoPriv or authPriv. |
| Auth proto, Auth key | Sha1, empty | Authentication: Md5, Sha1, Sha224, Sha256, Sha384 or Sha512, and its password. |
| Priv proto, Priv key | Aes128, empty | Encryption: Des, Aes128, Aes192 or Aes256, and its password. |
| Context name | empty | Leave it empty. |
Use SNMPv3 with authPriv, Sha256 or stronger and Aes128 or stronger where the device supports it. With v1 and v2c, keep the agents and the YTCC server in a protected network. The passwords are stored in the driver settings, so restrict who may edit the configuration.
Changing Host, Port, the version, the community or a v3 setting opens a new session at the next poll; changing Trap enabled or Trap bind reopens the trap port. The other parameters take effect at once.
Signal address
Set the address on the Value source tab of the signal, under Address — SNMP: the OID in numeric dotted form.
| OID | Meaning |
|---|---|
1.3.6.1.2.1.1.3.0 | sysUpTime of the agent (a single value ends in .0) |
1.3.6.1.2.1.2.2.1.10.3 | Bytes received on interface 3 (a table cell ends in the row index) |
Enter the numeric OID, which you find in the MIB of the device. A leading dot is ignored. In import files, write the OID in the address column.
Values
| SNMP type | Value in YTCC |
|---|---|
| Integer | Int64 |
| Counter32, Gauge32 / Unsigned32, TimeTicks | UInt32 |
| Counter64 | UInt64 |
| OCTET STRING | Text |
| IpAddress | Text, for example 192.168.0.95 |
| OBJECT IDENTIFIER | Text in dotted form |
| noSuchObject, noSuchInstance, endOfMibView, Null | No value; the signal is Bad |
Counters are shown as the agent reports them, as a running total. TimeTicks are hundredths of a second. To show a rate, such as bytes per second, derive it in a script or an expression signal.
Reading
Each poll reads every signal of the device with its own GET request, one after another. Many signals on one agent make a poll round long: keep the poll interval longer than the number of signals × the answer time of the agent. A value is used only from the answer to its own request; late answers are dropped.
Traps
With Trap enabled, the driver receives SNMPv1 and SNMPv2c traps on Trap bind. A trap is accepted only from an allowed source and with the community of the device. Each value in the trap whose OID is the OID of a signal of the device updates that signal; other values are ignored.
- On Linux, port 162 needs extra rights; use a port above 1023 and set it on the agent if you cannot grant them.
- Only one driver can use a port: give each SNMP driver that receives traps its own Trap bind port.
Writing
A signal can be written with SET when its Access is Read / Write or Write only. Integers and on/off values are sent as an Integer; text, fractions and 64-bit unsigned values are rejected. A command is rejected at once when the agent does not answer.
A refusal of the agent is shown with its reason: not writable, wrong type, value out of range or access denied. For how operators send and confirm commands, see Send commands.
Quality
| Situation | Quality |
|---|---|
| The agent returned the value | Good |
| The agent answered with an error or no such object | Bad; the last value stays |
| No answer, or an SNMPv3 authentication or encryption error | Bad · Not connected; the last value stays |
The device is marked not connected after three requests in a row are not answered and a test read of the last OID that answered also fails; one silent OID alone does not disconnect the device. The time of a value is the time it was received.
Diagnostics
Read now on the Value source tab sends one GET for the OID:
| Text | Meaning |
|---|---|
| SNMP GET and a value | The agent answered |
| Invalid SNMP address: '…' is not an OID | The OID is not in numeric dotted form |
| Cannot open SNMP session to … | Host not found, or the SNMPv3 settings are refused |
| Timeout — no response from … within … ms | No answer: wrong community, wrong address, firewall |
| SNMP error … (noSuchName / readOnly / noAccess / authorizationError …) | The agent refused the request |
| No such object | The OID does not exist on the agent, often a missing .0 or row index |
| Symptom | Likely cause |
|---|---|
| All signals Bad · Not connected, no error | Wrong community (the agent does not answer), UDP 161 blocked |
| SNMPv3 session cannot be opened | User, protocols or passwords differ from the agent |
| One signal Bad | OID wrong or not supported by the device |
| No traps arrive | Port 162 in use or not permitted; the trap comes from another address than Host (add it to Trap allowed sources) |
Supported operations
| Operation | Supported |
|---|---|
| GET | Yes |
| SET | Yes (integer, on/off) |
| Trap v1, v2c | Yes |
| SNMPv3 authentication: MD5, SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 | Yes |
| SNMPv3 encryption: DES, AES-128, AES-192, AES-256 | Yes |