How to write SNMP Plugins

This HOWTO is not quite done yet.

As writing a Munin plugin is simple writing a SNMP one is even simpler. The SNMP agent on the device has done all the hard work for us. We just need to be able to autodetect if a particular device supports our plugin, and then present the stats the SNMP agent gives us.

If you do not know or understand what SNMP is or what a community string is used for please find (and read) some general SNMP material before you go on.

Supporting library

If you have used SNMP plugins with Munin you may have noticed that there is a uniform way to configure them. This is implemented in the perl library Munin::Plugin::SNMP (Perl module) which is supplied in Munin 1.4.

If you run perldoc Munin::Plugin::SNMP you’ll see the programmers documentation for the module and its public functions - as usual. This also explains how to configure a plugin using this module for different authentications and versions of SNMP.

A load plugin

Returning to the absolute simplest case I would have picked a snmp__load plugin for this HOWTO, but not many devices supports that. Uptime on the other hand is very basic to SNMP devices. If you snmpwalk some device the uptime will be there among the first 10 lines:

DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (138007908) 15 days, 23:21:19.08

The numeric OID for that is

$ snmptranslate -On DISMAN-EVENT-MIB::sysUpTimeInstance
.1.3.6.1.2.1.1.3.0

A Perl script to get the basics

#! /usr/bin/perl

use strict;
use warnings;
use Munin::Plugin::SNMP;

my $session = Munin::Plugin::SNMP->session(-translate =>
                                           [ -timeticks => 0x0 ]);

my $uptime = $session->get_single (".1.3.6.1.2.1.1.3.0") || 'U';

if ($uptime ne 'U') {
    $uptime /= 8640000; # Convert to days
}

print "uptime.value ", $uptime, "\n";

The -translate option is to stop the SNMP stack from converting the timetics into a human readable time string, we want a integer to graph.

If you call this snmp__uptime and then in /etc/munin/plugins make a symlink to it: If your device is called “switch” (this should be in DNS (or the hosts file) and possible to look up): ln -s snmp_switch_uptime …

Then the plugin has to be configured, /etc/munin/plugin-conf.d/snmp for the imagined device called “switch”:

[snmp_*]
   env.version 2
   env.community public

Now you can do munin-run snmp_switch_uptime as root:

# munin-run snmp_switch_uptime
uptime.value 15.979475462963

You need a config section too.

if (defined $ARGV[0] and $ARGV[0] eq "config") {
    my ($host) = Munin::Plugin::SNMP->config_session();
        print "host_name $host\n" unless $host eq 'localhost';
        print "graph_title System Uptime
graph_args --base 1000 -l 0
graph_vlabel uptime in days
graph_category system
graph_info This graph shows the number of days that the the host is up and running so far.
uptime.label uptime
uptime.info The system uptime itself in days.
uptime.draw AREA
";
        exit 0;
}

That makes the plugin configurable. Please notice that the plugin prints a host_name line if it’s not examining the localhost. This is the way Munin knows which device a non-local plugin is examining.

All cool and good. Now we need it to autoconfigure for each new SNMP agent you configure for. In general you would run this command:

# munin-node-configure --snmp --snmpversion 2 --snmpcommunity public 192.168.2.0/24 | sh -x

This will interogate all IP addresses in the given CIDR range with the given SNMP version and community string and then the script figures out which SNMP plugins will work on a device it finds and makes goes ln -s snmp_switch_uptime /usr/share/munin/plugins/snmp__uptime if the device known as “switch” supports the uptime plugin.

The way it does this is by knowing which plugins to talk to, and then by asking them what OIDs they are interested in:

=head1 MAGIC MARKERS

  #%# family=snmpauto
  #%# capabilities=snmpconf

...

=cut

...

if (defined $ARGV[0] and $ARGV[0] eq "snmpconf") {
        print "require 1.3.6.1.2.1.1.3.0 [0-9]\n"; # Number
        exit 0;
}

Given those magic markers munin-node-configure will run the plugin with the argument snmpconf which makes the plugin tell munin-node-configure what OIDs it requires for operation.

In a more complex case, snmp__if_ more is needed to generate the needed symlinks:

# TODO