SNMP/en

SNMP (Simple Network Management Protocol) is a standard Protocol for managing network devices in IP networks.

It is often used to exchange service information with devices, presenting data as separate variables.

Protocol support is found in network switches, routers, uninterruptible power supply (UPS) systems, servers, etc.

A driver has been added to the Wiren Board to receive data from SNMP devices. The driver is written in Go.

Installation and configuration on the controller

Installation

First you need to install the wb-mqtt-snmp package. In the device console, enter

# apt-get update
# apt-get install wb-mqtt-snmp

Settings

The configuration structure is very similar to wb-mqtt-serial.

Example of the configuration file (/etc/wb-mqtt-snmp.conf):

{
    "debug": false,
    "num_workers": 4,
    "devices": [
        {
            "address": "192.168.0.1",
            "name": "My SNMP server",
            "community": "public",
            "oid_prefix": "SNMPv2-MIB",
            "channels": [
                {
                    "name": "Number of services",
                    "oid": "sysServices.0",
                    "poll_interval": 1000
                },
                {
                    "name": "Boot string",
                    "oid": "HOST-RESOURCES-MIB::hrSystemInitialLoadParameters.0",
                    "poll_interval": 10000
                },
                {
                    "name": "System location",
                    "oid": ".1.3.6.1.2.1.1.6.0"
                }
            ]
        },
        {
            "address": "test.net-snmp.org",
            "name": "Test SNMP server",
            "device_type": "test-snmp"
        }
    ]
}

Consider it more detailed.

Configuration file

• debug - flag to enable debug mode. If true, then in the process of the daemon in the log file will be put debug information (default is false);
• num_workers - maximum number of SNMP connections to be established at the same time.
  • If many SNMP devices are being polled, increasing this setting may speed up the polling. However, increasing this setting also increases the maximum load on the network. In General, you can leave the default value (4).
• devices - list of devices to be polled.

Device description

Parameter name	Type	Description	Required	Default
name	string	device name	No	SNMP [address]_[community]
id	string	device ID in MQTT	No	snmp_[address]_[community]
address	string	Network address of the device	Yes	-
device_type	string	Type of device (required for downloading the template)	No	-
enabled	bool	do you want to include the device in the poll?	No	true
community	string	community name SNMP	Yes	-
oid_prefix	string	Prefix (MIB name) for text OID channels where the prefix is explicitly specified	No	-
snmp_version	string	SNMP version (currently only 2C is supported )	No	2c
snmp_timeout	integer	response timeout (in seconds)	No	5
poll_interval	integer	Minimum polling time for each channel by default	No	-
channels	array	channels description (SNMP variables)	No	-

Channel description

Parameter name	Type	Description	Required	Default
name	string	channel name	Yes	-
oid	string	OID in numeric or text form	Yes	-
enabled	boolean	Include the channel in poll?	No	true
control_type	string	data type(according to Conventions)	No	text
units	string	the string name of the units(for control_type == value)	No	-
scale	float	Multiplier (for numeric values)	No	1.0
poll_interval	int	the polling interval of the channel (in ms)	No	poll_interval from the description of the device, or 1000

OID conversion

When the daemon is started, an attempt is made to convert the text OIDs recorded in the configuration into numeric ones.

If the OID is represented in numeric form (starts with the dot: .1.2.3.4), no conversion occurs.

If the OID is in text form (for example, SNMPv2-MIB::sysName.0), it is necessary that the appropriate MIB containing the description of this variable is installed on the system. The name conversion is done by calling the snmptranslate utility, so you can check for a MIB manually by using the command

# snmptranslate -On yourOid

Oid_prefix parameter in the device description allows you to omit the name of the MIB (prefix; SNMPv2-MIB::sysName.0). In this case, the prefix from oid_prefix will be automatically attached to all OID channels of the device where the prefix is not explicitly specified. For example, if oid_prefix = SNMPv2-MIB:

• sysName.0 -> SNMPv2-MIB::sysName.0
• sysLocation.0 -> SNMPv2-MIB::sysLocation.0
• HOST-RESOURCES-MIB::hrSystemUptime.0 -> HOST-RESOURCES-MIB::hrSystemUptime.0
• .1.3.6.1.2.1.1.6.0 -> .1.3.6.1.2.1.1.6.0

MIB installation

If You have the required MIB file, just copy it to the /root/.snmp/mibs, by pre-creating it:

# mkdir -p /root/.snmp/mibs
# cp your-mibs-file.mib /root/.snmp/mibs

After that, verify that snmptranslate works correctly with any known OID:

# snmptranslate -On yourOid

Templates

It is convenient (though not necessary) to use templates to describe devices. The template (device type) is an external configuration file (located in /usr/share/wb-mqtt-snmp/templates and named config-[device-type-name].json, for example, config-test-snmp.json), which contains a basic description of the device (such as the SNMP community name) and a basic description of all its channels.

To use the template in the device description in the configuration file, specify the field 'device_type'. Among all presented templates, a template with the same device_type value will be selected, and all fields that were not defined in the configuration file will take values from the template.

It works the same way with channels. The channels are compared by the mandatory field name; if the channel name from the configuration file matches the channel name in the template, all unspecified values will be taken from the template.

Example

Config-my-device.json template:

{
    "device_type": "my-device",
    "community": "public",
    "channels": [
        {
            "name": "Channel 1",
            "oid": ".1.2.3.4.1"
        },
        {
            "name": "Channel 2",
            "oid": ".1.2.3.4.2",
            "poll_interval": 3000
        }
    ]
}

Configuration file:

{
    "devices": [
        {
            "name": "Device 1",
            "device_type": "my-device",
            "address": "192.168.0.5",
            "snmp_timeout": 1
        },
        {
            "name": "Device 2",
            "device_type": "my-device",
            "address": "my-device.example.org",
            "snmp_timeout": 5,
            "channels": [
                {
                    "name": "Channel 2",
                    "poll_interval": 10000
                }
            ]
        }
    ]
}

In this case, we have described one my-device template, by which we have defined two different devices Device 1 and Device 2 with the same set of channels.

In this case, we have described one my-device template, by which we have defined two different devices Device 1 and Device 2 with the same set of channels.

Since Device 1 is on the local network, it is logical to set it a small timeout value to quickly determine the malfunction of the device. All other settings are taken from the template.

Device 2 and the remote server, because for him, it is necessary to increase the timeout to not think the device is faulty if the delay of the package. What's more, for channel 2 here, we are redefining the polling interval to a larger one to reduce the load on the network.

So, it is very convenient to use templates to describe a group of similar devices.

Template list

The WB-mqtt-snmp package includes a set of templates for typical devices (the list will be expanded):

Device	Template	Tested	Comments
Test server Net-SNMP	test-snmp	Yes	Test server address test.net-snmp.org
APC UPS	apc-ups	Нет	Requires locally installed PowerNet-MIB The device description is the same as in wb-mqtt-apcsnmp