Developing plugins to collect SNMP data

This is the third post about custom plugins. We recommend you to take a look at our previous posts about plugin development and usage.

The SNMP protocol is one of the most used methods to obtain monitoring information from various types of devices, such as servers, switches, routers, printers and temperature sensors. In this post, we’ll detail how to create a plugin that will connect to an SNMP device using credentials.

Creating a credential

The Unit Platform, by default, comes with an SNMP v2c credential with the “public” community. In case the community you are using in your environment is a different one, you must create a new credential. For that, you need to access the configuration menu and click on Credentials:

Click on “Add credential”. If the Unit Platform installation is in a multitenancy environment, select the company that will use the credential, then select the type of SNMP credential you’ll use. Unit Platform supports three types of SNMP credentials: SNMPv1, SNMPv2c e SNMPv3.

For every credential type, a different set of information will be required. In this simple example, we’ll use SNMPv2c. Create a credential following the example below:

Using SNMP credentials

To use a credential, we must create a plugin that’s able to receive a string argument. This string will contain all the credential’s variables separated by “;”. Every SNMP credential type is listed below, along with the credential’s formats:

• SNMP v1: snmpv1;[community]
• SNMP v2c: snmpv2c;[community]
• SNMP v3: snmpv3;[username];[security level];[authentication method];[authentication password];[cryptography method];[cryptography password]
  • security level: authpriv, authnopriv or noauthnopriv
  • authentication method: sha or md5
  • cryptography method: 3desede, aes128, aes192, aes256, des or idea

Programming the plugin

Below is an example of a plugin that checks device uptime through SNMP. It’s a prerequisite that the monitored device has the SNMP service running and that the Unit Platform server has access to the same device’s 161 / UDP port.

The plugin’s written in Bash and will run locally on the Unit Platform. This plugin works for all SNMP versions and is named my_first_plugin_snmp.sh.

#!/bin/bash

address=$1
credential=$2

snmpVersion=$(echo $credential | cut -d ";" -f 1)

if [ "$snmpVersion" == "snmpv1" ]; then
    snmpCommunity=$(echo "$credential" | cut -d ";" -f2)
    snmpArgs="-v1 -c $snmpCommunity"
fi

if [ "$snmpVersion" == "snmpv2c" ]; then
    snmpCommunity=$(echo "$credential" | cut -d ";" -f2)
    snmpArgs="-v2c -c $snmpCommunity"
fi

if [ "$snmpVersion" == "snmpv3" ]; then
    snmpUser=$(echo "$credential" | cut -d ";" -f2)
    snmpLevel=$(echo "$credential" | cut -d ";" -f3)
    snmpTypeAuth=$(echo "$credential" | cut -d ";" -f4)
    snmpPassAuth=$(echo "$credential" | cut -d ";" -f5)
    snmpTypeCrypt=$(echo "$credential" | cut -d ";" -f6)
    snmpPassCrypt=$(echo "$credential" | cut -d ";" -f7)

    [ "$snmpLevel" == "noauthnopriv" ] && snmpArgs="-v3 -u $snmpUser -l $snmpLevel"
    [ "$snmpLevel" == "authnopriv" ] &&   snmpArgs="-v3 -u $snmpUser -l $snmpLevel -a $snmpTypeAuth -A $snmpPassAuth"
    [ "$snmpLevel" == "authpriv" ] &&     snmpArgs="-v3 -u $snmpUser -l $snmpLevel -a $snmpTypeAuth -A $snmpPassAuth -x $snmpTypeCrypt -X $snmpPassCrypt"
fi

result=$(snmpget -OevQ $address $snmpArgs sysUpTimeInstance)

echo $result

This plugin has two entry arguments: address and credential. These parameters must be specified in the plugin’s command line during the plugin’s upload.

More details about plugin development can be seen here in this post.

Uploading the plugin

To register this code as a plugin, the steps to be followed are almost the same as described here, the only different thing’s that we’ll select SNMPv2c as the credential type:

Item 1 – Company: select the company that will make use of the plugin.

Item 2 – Plugin name: choose a name for the plugin.

Item 3 – Credential type: select the credential type the plugin supports. In this example, we’ll use SNMPv2c.

Item 4 – Send Script: upload the file “my_first_plugin_snmp.sh”.

Item 5 – Command line arguments: The variable “address” must be used because when the monitored item is executed, the plugin will connect to the desired machine. In addition to this variable, we’ll also use the “credential”, which will be the string with all the necessary variables separated by “;”.

Click on “Test plugin”.

On the test execution interface, all credentials of the type chosen in the previous screen will be displayed. Select the credential that was created before, as well as a device to point the test to. Click on “Execute test”.

By successfully completing the test, proceed to the next steps of the plugin creation wizard to specify the plugin output and monitoring rules. For more details about plugin usage, we recommend reading this post.