SNMP Binding

This binding integrates the Simple Network Management Protocol (SNMP). SNMP can be used to monitor or control a large variety of network equipment, e.g. routers, switches, NAS-systems. Currently protocol version 1 and 2c are supported.

Supported Things

Only one thing is supported: target. It represents a single network device. Things can be extended with number, string and switch channels.

Binding Configuration

If only GET/SET-requests shall be used, no configuration is necessary. In this case the port parameter defaults to 0.

For receiving traps a port for receiving traps needs to be configured. The standard port for receiving traps is 162, however binding to ports lower than 1024 is only allowed with privileged right on most *nix systems. Therefore it is recommended to bind to a port higher than 1024 (e.g. 8162). In case the trap sending equipment does not allow to change the destination port (e.g. Mikrotik routers), it is necessary to forward the received packets to the new port. This can be done either by software like snmptrapd or by adding a firewall rule to your system, e.g. by executing

iptables -t nat -I PREROUTING --src 0/0 --dst 192.168.0.10 -p udp --dport 162 -j REDIRECT --to-ports 8162

would forward all TCP packets addressed to 192.168.0.10 from port 162 to 8162. Check with your operating system manual how to make that change permanent.

Example configuration for using port 8162:

# Configuration for the SNMP Binding
#
# Port used for receiving traps.
# This setting defaults to 0 (disabled / not receiving traps)
port=8162

Thing Configuration

The target thing has one mandatory parameter: hostname. It can be set as FQDN or IP address.

Optional configuration parameters are community, version and refresh.

The SNMP community can be set with the community parameter. It defaults to public.

Currently two protocol versions are supported. The protocol version can be set with the protocol parameter. The allowed values are v1 or V1for v1 and v2c or V2C for v2c. The default is v1.

By using the refresh parameter the time between two subsequent GET requests to the target can be set. The default is 60 for 60s.

Three advanced parameters are available port, timeout, retries Usually these do not need to be changed.

If the SNMP service on the target is running on a non-standard port, it can be set with the port parameter. It defaults to 161.

By using the timeout and retries parameters the timeout/error behaviour can be defined. A single request times out after timeout ms. After retries timeouts the refresh operation is considered to be fails and the status of the thing set accordingly. The default values are timeout=1500 and retries=2.

Channels

The target thing has no fixed channels. It can be extended with channels of type number, string, switch.

All channel-types have one mandatory parameter: oid. It defines the OID that should be linked to this channel in dotted format (e.g. .1.2.3.4.5.6.8).

Channels can be configured in four different modes via the mode parameter. Available options are READ, WRITE, READ_WRITE and TRAP. READ creates a read-only channel, i.e. data is requested from the target but cannot be written. WRITE creates a write-only channel, i.e. the status is never read from the target but changes to the item are written to the target. READ_WRITE allows reading the status and writing it for controlling remote equipment. TRAP creates a channel that ONLY reacts to traps. It is never actively read and local changes to the item's state are not written to the target. UsingTRAP channels requires configuring the receiving port (see "Binding configuration").

The datatype parameter is needed in some special cases where data is written to the target. The default datatype for number channels is UINT32, representing an unsigned integer with 32 bit length. Alternatively INT32 (signed integer with 32 bit length), COUNTER64 (unsigned integer with 64 bit length) or FLOAT (floating point number) can be set. Floating point numbers have to be supplied (and will be send) as strings. For string channels the default datatype is STRING (i.e. the item's will be sent as a string). If it is set to IPADDRESS, an SNMP IP address object is constructed from the item's value. The HEXSTRING datatype converts a hexadecimal string (e.g. aa bb 11) to the respective octet string before sending data to the target (and vice versa for receiving data).

number-type channels can have a parameter unit if their mode is set to READ. This will result in a state update applying UoM (opens new window) to the received data if the UoM symbol is recognised.

switch-type channels send a pre-defined value if they receive ON or OFF command in WRITE or READ_WRITE mode. In READ, READ_WRITE or TRAP mode they change to either ON or OFF on these values. The parameters used for defining the values are onvalue and offvalue. The datatype parameter is used to convert the configuration strings to the needed values.

type	item	description
number	Number	a channel with a numeric value
string	String	a channel with a string value
switch	Switch	a channel that has two states

SNMP Exception (Error) Handling

The standard behaviour if an SNMP exception occurs this is to log at INFO level and set the channel value to UNDEF. This can be adjusted at channel level with advanced options.

The logging can be suppressed with the doNotLogException parameter. If this is set to true any SNMP exception is not considered as faulty. The default value is false.

By setting exceptionValue the default UNDEF value can be changed. Valid values are all valid values for that channel (i.e. ON/OFF for a switch channel, a string for a string channel and a number for a number channel).

Full Example

demo.things:

Thing snmp:target:router [ hostname="192.168.0.1", protocol="v2c" ] {
    Channels:
        Type number : inBytes [ oid=".1.3.6.1.2.1.31.1.1.1.6.2", mode="READ", unit="B" ]
        Type number : outBytes [ oid=".1.3.6.1.2.1.31.1.1.1.10.2", mode="READ" ]
        Type number : if4Status [ oid="1.3.6.1.2.1.2.2.1.7.4", mode="TRAP" ]
        Type switch : if4Command [ oid="1.3.6.1.2.1.2.2.1.7.4", mode="READ_WRITE", datatype="UINT32", onvalue="2", offvalue="0" ]
        Type switch : devicePresent [ oid="1.3.6.1.2.1.2.2.1.221.4.192.168.0.1", mode="READ", datatype="UINT32", onValue="1", doNotLogException="true", exceptionValue="OFF" ]
        Type switch : valueReceived [ oid="1.3.6.1.2.1.2.2.1.221.17.5", mode="READ", datatype="HEXSTRING", onValue="00 AA 11", offValue="00 00 00" ]
}

demo.items:

Number inBytes "Router bytes in [%d]" { channel="snmp:target:router:inBytes" }
Number inGigaBytes "Router gigabytes in [%d GB]" { channel="snmp:target:router:inBytes" }
Number outBytes "Router bytes out [%d]" { channel="snmp:target:router:outBytes" }
Number if4Status "Router interface 4 status [%d]" { channel="snmp:target:router:if4Status" }
Switch if4Command "Router interface 4 switch [%s]" { channel="snmp:target:router:if4Command" }
Switch devicePresent "Phone connected [%s]" { channel="snmp:target:router:devicePresent" }
Switch receivedValue "Received 00 AA 11 [%s]" { channel="snmp:target:router:valueReceived" }

demo.sitemap:

sitemap demo label="Main Menu"
{
    Frame {
        Text item=inBytes
        Text item=outBytes
        Text item=if4Status
        Switch item=if4Command
        Text item=devicePresent
        Text item=receivedValue
    }
}

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)