/ 
Monitoring-Sneck-1.5.0
/ Monitoring::Sneck

NAME

Monitoring::Sneck - a boopable LibreNMS JSON style SNMP extend for remotely running nagios style checks

VERSION

Version 1.5.0

SYNOPSIS

use Monitoring::Sneck;

my $file='/usr/local/etc/sneck.conf';

my $sneck=Monitoring::Sneck->new({config=>$file});

USAGE

Not really meant to be used as a library. The library is more of to support the script.

CONFIG FORMAT

See Monitoring::Sneck::Config for the config format and a example.

USAGE

snmpd should be configured as below.

extend sneck /usr/bin/env PATH=/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin /usr/local/bin/sneck -c

Then just setup a entry in like cron such as below.

*/5 * * * * /usr/bin/env PATH=/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin /usr/local/bin/sneck -u 2> /dev/null > /dev/null

Most likely want to run it once per polling interval.

You can use it in a non-cached manner with out cron, but this will result in a longer polling time for LibreNMS or the like when it queries it.

RETURN HASH

The data section of the return hash is as below.

- $hash{data}{alert} :: 0/1 boolean for if there is a aloert or not.

- $hash{data}{ok} :: Count of the number of ok checks.

- $hash{data}{warning} :: Count of the number of warning checks.

- $hash{data}{critical} :: Count of the number of critical checks.

- $hash{data}{unknown} :: Count of the number of unkown checks.

- $hash{data}{errored} :: Count of the number of errored checks.

- $hash{data}{alertString} :: The cumulative outputs of anything
  that returned a warning, critical, or unknown.

- $hash{data}{vars} :: A hash with the variables to use.

- $hash{data}{time} :: Time since epoch.

- $hash{data}{hostname} :: The hostname the check was ran on.

- $hash{data}{config} :: The raw config file if told to include it.

- $hash{data}{run_time} :: How long it took to run all checks.

- $hash{data}{restarted} :: Count of the number of restarts ran.

- $hash{data}{restart_state_error} :: Only present if the restart
  state file could not be read or written. Restarts still run if it
  can't be read, as if there was no state.

For below '$name' is the name of the check in question.

- $hash{data}{checks}{$name} :: A hash with info on the checks ran.

- $hash{data}{checks}{$name}{check} :: The command pre-variable substitution.

- $hash{data}{checks}{$name}{ran} :: The command ran.

- $hash{data}{checks}{$name}{output} :: The output of the check.

- $hash{data}{checks}{$name}{exit} :: The exit code. If it died on a
  signal, this is 128 plus the signal number. If it could not be
  executed, this is -1.

- $hash{data}{checks}{$name}{error} :: Only present it died on a
  signal or could not be executed. Provides a brief description.

- $hash{data}{checks}{$name}{run_time} :: How long it took to run the checks.

- $hash{data}{checks}{$name}{rechecked_by} :: Only present if it was
  rerun after a restart with check_restart set. The name of that
  restart. The rest of the results are from the rerun.

For below '$name' is the name of the debug checks in question.

- $hash{data}{debugs}{$name} :: A hash with info on the checks ran.

- $hash{data}{debugs}{$name}{check} :: The command pre-variable substitution.

- $hash{data}{debugs}{$name}{ran} :: The command ran.

- $hash{data}{debugs}{$name}{output} :: The output of the check.

- $hash{data}{debugs}{$name}{exit} :: The exit code. Same as for checks.

- $hash{data}{debugs}{$name}{error} :: Only present it died on a
  signal or could not be executed. Provides a brief description.

- $hash{data}{debugs}{$name}{run_time} :: How long it took to run the debug.

For below '$name' is the name of the restart in question. Every restart in the config has a entry, even when restarts are disabled.

- $hash{data}{restarts}{$name}{triggered} :: 0/1 for if enough of its
  checks failed to meet its threshold.

- $hash{data}{restarts}{$name}{ran} :: 0/1 for if it ran.

- $hash{data}{restarts}{$name}{reason} :: Why it did or did not run.
  One of 'threshold', 'cascade from $depend', 'cooldown, $N seconds
  left', 'max retries reached', 'skipped, dependency $depend failed',
  'maintenance window', 'not triggered', or 'restarts disabled'.

- $hash{data}{restarts}{$name}{failed_checks} :: Array of the watched
  checks that counted as failed.

- $hash{data}{restarts}{$name}{threshold} :: The threshold.

- $hash{data}{restarts}{$name}{attempts} :: Runs for its threshold
  since its checks last recovered.

- $hash{data}{restarts}{$name}{command} :: The command pre-variable
  substitution.

The rest are only present if it ran.

- $hash{data}{restarts}{$name}{ran_command} :: The command ran.

- $hash{data}{restarts}{$name}{output} :: The output of the command.

- $hash{data}{restarts}{$name}{exit} :: The exit code. Same as for
  checks, plus -1 if it timed out.

- $hash{data}{restarts}{$name}{error} :: Only present if it timed
  out, died on a signal, or could not be executed. If it timed out
  and timeout_signal is set, also says the signal was sent, plus
  any problems sending it. Also present if check_restart is set,
  the command exited 0, and its checks still met the threshold
  afterwards.

- $hash{data}{restarts}{$name}{run_time} :: How long the command
  took to run, not counting check_restart.

- $hash{data}{restarts}{$name}{recheck_failed_checks} :: Only present
  if check_restart is set. Array of the watched checks that still
  counted as failed when rerun.

A restart that ran and failed, including timing out or its checks still failing with check_restart, sets alert and adds a line to alertString along with any output from the command. Check results, counts, and alertString reflect any checks rerun by check_restart.

METHODS

new

Initiates the object.

One argument is taken and that is a hash ref. If the key 'config' is present, that will be the config file used. Otherwise '/usr/local/etc/sneck.conf' is used. The key 'include' is a Perl boolean for if the raw config should be included in the JSON.

This function should always work as long as it can read the config. If there is an error with parsing or the like, it will be reported in the expected format when $sneck->run is called.

This is meant to be rock solid and always work, meaning LibreNMS style JSON is always returned(provided Perl and the other modules are working).

If 'debug' is true, when run is called, debugging info will be printed.

If 'restart' is true, restarts whose checks failed are run. Otherwise they are only reported. Never enable this for something polled by snmpd.

'state_file' is where restart state, used for min_interval and max_retries, is kept. Default :: /var/cache/sneck.cache.restarts

my $sneck;
eval{
    $sneck=Monitoring::Sneck->new({config=>$file, include=>0, debug=>0, restart=>0});
};
if ($@){
    die($@);
}

run

This runs the checks and returns the return hash.

my $return=$sneck->run;

AUTHOR

Zane C. Bowers-Hadley, <vvelox at vvelox.net>

BUGS

Please report any bugs or feature requests to bug-monitoring-sneck at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Monitoring-Sneck. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Monitoring::Sneck

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This software is Copyright (c) 2023 by Zane C. Bowers-Hadley.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)