This page is part of archived documentation for openHAB 3.3. Go to the current stable version
# 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 V1
for 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
}
}