snmp__apc_ups

#!/usr/bin/perl

=head1 NAME

snmp__apc_ups - Munin multigraph plugin for APC UPSes

=head1 APPLICABLE SYSTEMS

The UPS must support the PowerNet-MIB published by APC.  This includes
the APC Smart-UPS series on which this plugin was tested.

=head1 CONFIGURATION

As a rule SNMP plugins need site specific configuration.  The default
configuration (shown here) will only work on insecure sites/devices.

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

In general SNMP is not very secure at all unless you use SNMP version
3 which supports authentication and privacy (encryption).  But in any
case the community string for your devices should not be "public".

Please see 'perldoc Munin::Plugin::SNMP' for further configuration
information.

=head1 INTERPRETATION

Please refer to the PowerNet-MIB when in doubt.

=head1 MIB INFORMATION

This plugin requires support for the PowerNet-MIB published by APC.

=head1 PROGRAMMERS

This plugin is actually a generic SNMP multigraph plugin.  If you
customize the data structures, especially %oidList and %label which is
used to drive the loops.  Take care that labels and structure of these
hashes match otherwise things will disappear with not much warning.
But se munin-node.log, munin-update.log and run the plugin with
munin-run.

=head1 MAGIC MARKERS

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

=head1 BUGS

Probably.

=head1 AUTHOR

Based on work by Gorlow Maxim and Andrey Yakovlev.  Totaly reworked by
Nicolai Langfeldt, BroadNet AS, Oslo, Norway.

  Copyright (C) 2013 Nicolai Langfeldt, BroadNet AS

=head1 LICENSE

GPLv2 only.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; version 2 dated June, 1991.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
USA.

=cut

use strict;
use warnings;

use feature qw(say);

use Carp;
use Data::Dumper;

use Munin::Plugin;
use Munin::Plugin::SNMP;

use vars qw($DEBUG);

$DEBUG = $Munin::Plugin::DEBUG;

# ################ Change here to customize

# oidList - things to graph - must be complete

my %oidList =
  # _meta will be fetched but not graphed. The values can be placed in
  # texts by [OID:1.3.6.....] notation in any text in the "config"
  # output from the plugin. _meta is not used anywhere else than for
  # this.
  ( _meta =>
    { upsBasicIdentModel             => '1.3.6.1.4.1.318.1.1.1.1.1.1.0',
      upsAdvIdentSerialNumber        => '1.3.6.1.4.1.318.1.1.1.1.2.3.0',
      upsAdvConfigRatedOutputVoltage => '1.3.6.1.4.1.318.1.1.1.5.2.1.0', # 230
      upsAdvConfigHighTransferVolt   => '1.3.6.1.4.1.318.1.1.1.5.2.2.0', # 208
      upsAdvConfigLowTransferVolt    => '1.3.6.1.4.1.318.1.1.1.5.2.3.0', # 253
    },
    time =>
    { upsAdvBatteryRunTimeRemaining => '1.3.6.1.4.1.318.1.1.1.2.2.3.0',
      upsAdvConfigLowBatteryRunTime => '1.3.6.1.4.1.318.1.1.1.5.2.8.0' },
    volt =>
    { upsAdvOutputVoltage           => '1.3.6.1.4.1.318.1.1.1.4.2.1.0',
      upsAdvInputLineVoltage        => '1.3.6.1.4.1.318.1.1.1.3.2.1.0',
      upsAdvInputMaxLineVoltage     => '1.3.6.1.4.1.318.1.1.1.3.2.2.0',
      upsAdvInputMinLineVoltage     => '1.3.6.1.4.1.318.1.1.1.3.2.3.0' },
    batteryvolt =>
    { upsAdvBatteryActualVoltage    => '1.3.6.1.4.1.318.1.1.1.2.2.8.0' },
    frequency =>
    { upsAdvOutputFrequency         => '1.3.6.1.4.1.318.1.1.1.4.2.2.0',
      upsAdvInputFrequency          => '1.3.6.1.4.1.318.1.1.1.3.2.4.0' },
    status =>
    { upsBasicOutputStatus          => '1.3.6.1.4.1.318.1.1.1.4.1.1.0',
      upsBasicBatteryStatus         => '1.3.6.1.4.1.318.1.1.1.2.1.1.0',
      upsAdvBatteryReplaceIndicator => '1.3.6.1.4.1.318.1.1.1.2.2.4.0',
      upsCommStatus                 => '1.3.6.1.4.1.318.1.1.1.8.1.0',
      upsAdvTestDiagnosticsResults  => '1.3.6.1.4.1.318.1.1.1.7.2.3.0' },
    temperature =>
    { upsAdvBatteryTemperature      => '1.3.6.1.4.1.318.1.1.1.2.2.2.0',
      iemStatusProbeCurrentTemp     => '1.3.6.1.4.1.318.1.1.10.2.3.2.1.4.1' },
    load =>
    { upsAdvOutputLoad              => '1.3.6.1.4.1.318.1.1.1.4.2.3.0',
      upsAdvBatteryCapacity         => '1.3.6.1.4.1.318.1.1.1.2.2.1.0' },
    current =>
    { upsAdvOutputCurrent           => '1.3.6.1.4.1.318.1.1.1.4.2.4.0',
      upsAdvBatteryCurrent          => '1.3.6.1.4.1.318.1.1.1.2.2.9.0',
      upsAdvTotalDCCurrent          => '1.3.6.1.4.1.318.1.1.1.2.2.10.0' },
  );

# Customize data series labels here.  Must be complete otherwise the
# data series will not appear in graphs.

my %label  =
  ( time        => { upsAdvBatteryRunTimeRemaining => 'Time left',
		     upsAdvConfigLowBatteryRunTime => 'Alarm' },
    volt        => { upsAdvOutputVoltage           => 'Output',
		     upsAdvInputLineVoltage        => 'Input',
		     upsAdvInputMaxLineVoltage     => 'Max In',
		     upsAdvInputMinLineVoltage     => 'Min In' },
    batteryvolt => { upsAdvBatteryActualVoltage    => 'Battery' },
    frequency   => { upsAdvOutputFrequency         => 'Output',
		     upsAdvInputFrequency          => 'Input' },
    status      => { upsBasicOutputStatus          => 'Output',
		     upsBasicBatteryStatus         => 'Battery',
		     upsCommStatus                 => 'Comms',
		     upsAdvTestDiagnosticsResults  => 'Diag',
		     upsAdvBatteryReplaceIndicator => 'Replace' },
    temperature => { upsAdvBatteryTemperature      => 'Battery',
		     iemStatusProbeCurrentTemp     => 'Probe' },
    load        => { upsAdvOutputLoad              => 'Usage',
		     upsAdvBatteryCapacity         => 'Total' },
    current     => { upsAdvOutputCurrent           => 'Output',
		     upsAdvBatteryCurrent          => 'Battery',
		     upsAdvTotalDCCurrent          => 'Total DC' }
  );


# http://munin-monitoring.org/wiki/fieldname.type for more
# information.  Overrides here:

# Default
my $tstype = 'GAUGE';

# Overrides
my %tstype = ();

# How to draw.
#
# By default drawing is LINE1, overrides here.  It will be hard to do
# the STACK types in this plugin since they are ordering sensitive.
# If you want that you will need to expand this plugin to define and
# use a %ordering hash that enforces field order so that stacks come
# out right.

my %tsdraw =
  (
    batteryvolt => { upsAdvBatteryActualVoltage    => 'LINE2' },
  );

# Minimum and maximum values.  Values outside the ragne given by these
# will be tossed.  None needed by default, add as needed in the same
# nested fashion as %label.

my %tsmin  = ();

my %tsmax  = ();

# Example:
#
# my %tsmin =
#  ( temperature => { upsAdvBatteryTemperature      => 10 } );
#
# my %tsmax =
#  ( temperature => { upsAdvBatteryTemperature      => 150 } );

# Warning and Critical ranges.  None needed by default.  Add as
# needed.

my %tswarn =
  ( status      => { upsBasicOutputStatus => '2:5' },
    time        => { upsAdvBatteryRunTimeRemaining => '90:' },
  );


my %tscrit =
  ( status      => { upsAdvBatteryReplaceIndicator => '1:1',
		     upsBasicBatteryStatus         => '2:2',
		     upsBasicOutputStatus          => '2:6',
		     upsCommStatus                 => '1:1',
		     upsAdvTestDiagnosticsResults  => '1:1' },

    frequency   => { upsAdvInputFrequency          => '49:51',
		     upsAdvOutputFrequency         => '49:51' },

    time        => { upsAdvBatteryRunTimeRemaining => '60:' },

    volt        => { upsAdvOutputVoltage =>
		     '[OID:1.3.6.1.4.1.318.1.1.1.5.2.3.0]:'.
		     '[OID:1.3.6.1.4.1.318.1.1.1.5.2.2.0]',
		     upsAdvInputLineVoltage =>
		     '[OID:1.3.6.1.4.1.318.1.1.1.5.2.3.0]:'.
		     '[OID:1.3.6.1.4.1.318.1.1.1.5.2.2.0]' },
  );

my %cdef   =
  ( time   =>
    { upsAdvBatteryRunTimeRemaining => 'upsAdvBatteryRunTimeRemaining,6000,/',
      upsAdvConfigLowBatteryRunTime => 'upsAdvConfigLowBatteryRunTime,6000,/' }
	   );


my %title  =
  ( time        => 'Time left on battery',
    volt        => 'Line Voltages',
    batteryvolt => 'Battery Voltage',
    frequency   => 'Line frequency',
    status      => 'Status codes',
    temperature => 'Temperatures',
    load        => 'Load/Capacity',
    current     => 'Currents'
  );

# Vertical labels on the graph

my %vlabel =
  ( time        => 'minutes',
    volt        => 'Volt',
    batteryvolt => 'Volt',
    frequency   => 'Hz',
    status      => 'code value',
    temperature => 'Celsius',
    load        => 'Percent',
    current     => 'Ampere',
  );

# Extra information on the whole graph.

my %info   =
  ( time        => 'Time left on battery and when shutdown occurs. In minutes.',
    volt        => 'Current input and output voltages.  The min and max '.
                   'readings are for the last minute.  Note that the values '.
                   'are collected every 5 minutes. Nominal voltage is '.
                   '[OID:1.3.6.1.4.1.318.1.1.1.5.2.1.0]',
    status      => 'Coded statuses.  UPS Model: '.
                   '[OID:1.3.6.1.4.1.318.1.1.1.1.1.1.0]. '.
                   'Serial number: [OID:1.3.6.1.4.1.318.1.1.1.1.2.3.0]',
    load        => 'Current load and capacity on/of the UPS in percent.',
    current     => 'The current in amperes.',
    temperature => 'Current temperatures.  Possebly only the battery.',
    batteryvolt => 'Current battery bus DC voltage.  For a 24V battery pack '.
                   'this should be around 26-27V.',
    frequency   => 'Current input and output AC frequency',
	      );

# Extra information for a time series

my %subinfo =
  ( load =>
    { upsAdvOutputLoad      => 'The current UPS load expressed in percent '.
                               'of rated capacity.',
      upsAdvBatteryCapacity => 'The remaining battery capacity expressed '.
                               'in percent of full capacity.' },
    status =>
    { upsBasicOutputStatus  => 'Codes: 1: unknown, 2: onLine (GREEN), '.
		'3: onBattery (YELLOW) 4: onSmartBoost 5: timedSleeping, '.
		'6: softwareBypass 7: off 8: rebooting, '.
		'9: switchedBypass 10: hardwareFailureBypass, '.
		'11: sleepingUntilPowerReturn 12: onSmartTrim '.
		'13: ecoMode 14: hotStandby 15: onBatteryTest',

      upsBasicBatteryStatus => 'The status of the UPS batteries.  A '.
		'batteryLow(3) value indicates the UPS will be unable '.
                'to sustain the current load, and its services will be '.
                'lost if power is not restored. The amount of run time '.
                'in reserve at the time of low battery can be configured '.
                'by the upsAdvConfigLowBatteryRunTime.',

      upsAdvBatteryReplaceIndicator => 'Battery replacement indicator. '.
                '1: All OK  2: Battery needs replacing',

      upsCommStatus => "The status of agent's communication ".
                'with UPS. 1: OK  2: Failed',

      upsAdvTestDiagnosticsResults => 'The results of the last UPS '.
                'diagnostics test performed. 1: OK, 2: Failed, '.
                '3: invalidTest, 4: testInProgress' },

    time =>
    { upsAdvBatteryRunTimeRemaining => 'The UPS battery run time '.
                'remaining before battery exhaustion.',
      upsAdvConfigLowBatteryRunTime => 'The desired run time of the UPS, '.
		'in minutes, once the low battery condition is reached. '.
                'During this time the UPS will produce a constant warning '.
                'tone which can not be disabled.' },
    current =>
    { upsAdvOutputCurrent => "The current in Amperes drawn by the load on the UPS.",
      upsAdvBatteryCurrent => "The battery current in Apmeres.",
      upsAdvTotalDCCurrent => "The total DC current in Amperes.", },
  );

# Extinfo is presented in conjunction with the time series information
# under the graph.  Usually it supplies extra information specific to
# a fault, but it might also provide any information for any reason.

my %extinfo =
  ( status =>
    { upsAdvTestDiagnosticsResults => "Last diagnostic performed [OID:1.3.6.1.4.1.318.1.1.1.7.2.4.0]" } );

# ########################## Code here

sub collect_snmp {
    # Mash together all the OIDs needed by the different graphs and
    # make a (one) query to get them all.  Returns a hash of the
    # values keyed by OID.
    #
    # Occurrences of "noSuchInstance" is replaced by "U".

    my ( $snmp ) = @_;

    my @oids = ();

    foreach my $graph ( keys %oidList ) {
	foreach my $oid ( values %{ $oidList{$graph} } ) {
	    push(@oids, $oid);
	}
    }

    my $values = $snmp->get_request( -varbindlist => \@oids );

    if ( $snmp->error() ) {
	die "$Munin::Plugin::me: SNMP error ".$snmp->error();
    }

    # Modify $values in place
    map { $values->{$_} = 'U'
	    if $values->{$_} eq 'noSuchInstance'; } keys %$values;

    return $values;
}


sub emit_a_fetch {
    # Emit just one value line
    my ( $text, $values, $key, $default ) = @_;

    my $value = $values->{$key};
    $value    = $default if ! defined $value;
    $value    = 'U'      if ! defined $value;

    say "$text $value";
}


sub emit_fetch {
    # Spew out
    my ( $graph, $oids, $values ) = @_;

    foreach my $label (keys %$oids) {
	emit_a_fetch( "$label.value", $values, $oids->{$label}, 'U' );
    }
}


sub emit_fetches {
    # Emit all the fetches for all the multigraphs
    my ( $snmp, $oids ) = @_;

    my $values = collect_snmp( $snmp, $oids );

    foreach my $graph (keys %label) {
	say "multigraph $graph";
	emit_fetch ( $graph, $oids->{$graph}, $values );
	say '';
    }
}


sub replace_oid {
    my ( $str, $values ) = @_;

    # If "str is [OID:1.3.6.1.2.1.1.5.0] then return the contents of sysName.0

    my $oid = substr( $str, 5, -1 );
    $str = $values->{$oid};

    return $str;
}


sub process_oids {
    my ( $str, $values ) = @_;

    if ( ! defined $values ) {
	croak("no values");
    }

    if ( $str =~ m/OID:/ ) {
	$str =~ s/(\[OID:[^]]*])/&replace_oid($1, $values)/eg;
    }

    return $str;
}


sub emit_a_config {
    # Emit a config line
    # IF there is a default, always emit line.
    # IF there is no default, only emit line if the hash lookup
    # exists.
    my ( $values, $text, $hash, $graph, $label, $default ) = @_;

    if ( defined $default ) {
	my $value = $hash->{$graph}->{$label};
	$value    = $default if ! defined $value;
	$value    = 'U'      if ! defined $value;

	say process_oids( "$text $value", $values );
	return;
    }

    if ( exists $hash->{$graph}->{$label} ) {
	say process_oids( "$text " . $hash->{$graph}->{$label}, $values );
    }
}


sub emit_config {
    # Emit a graph configuration
    my ( $graph, $values ) = @_;

    say "graph_title ".( $title{$graph} || "Untitled /$graph/");
    say process_oids( "graph_vlabel " . $vlabel{$graph}, $values );
    say "graph_category sensors";
    say process_oids( "graph_info " . $info{$graph}, $values );

    foreach my $label (keys %{ $label{$graph} } ) {
	emit_a_config( $values, "$label.label", \%label, $graph, $label,
		       $label );
	emit_a_config( $values, "$label.draw",  \%tsdraw, $graph, $label,
		       'LINE1'  );
	emit_a_config( $values, "$label.type",  \%tstype, $graph, $label,
		       $tstype );
	emit_a_config( $values, "$label.min",   \%tsmin,  $graph, $label );
	emit_a_config( $values, "$label.max",   \%tsmax,  $graph, $label );
	emit_a_config( $values, "$label.cdef",  \%cdef,   $graph, $label );
	emit_a_config( $values, "$label.info",  \%subinfo,$graph, $label );

	emit_a_config( $values, "$label.warning",  \%tswarn, $graph, $label );
	emit_a_config( $values, "$label.critical", \%tscrit, $graph, $label );
    }
}


sub emit_configs {
    my ( $snmp, $oids, $host, $results ) = @_;

    my $values = collect_snmp( $snmp, $oids );

    say "host_name $host";
    say "";

    foreach my $graph (keys %label) {
	say "multigraph $graph";
	emit_config( $graph, $values );

	# If dirty config allowed:
	emit_fetch ( $graph, $oids->{$graph}, $values );

	say '';
    }
}


sub main {
    # need_multigraph();

    if ($ARGV[0] and $ARGV[0] eq 'snmpconf') {
	say "require 1.3.6.1.4.1.318.1.1.1.2.2.8.0 [0-9]";
	exit 0;
    }

    my ( $host, undef ) = Munin::Plugin::SNMP::config_session();

    # Ensure that we get times in ticks (hundredths of a second)
    my $session =
      Munin::Plugin::SNMP->session( -translate => [ -timeticks => 0x0 ] );


    if ($ARGV[0] and $ARGV[0] eq 'config') {
	emit_configs( $session, \%oidList, $host );
	exit 0;
    }

    emit_fetches( $session, \%oidList );
    exit 0;
}



main();