/ 
Monitoring-Sneck-1.7.0
/ Monitoring::Sneck

NAME

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

VERSION

Version 1.7.0

SYNOPSIS

use Monitoring::Sneck;

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

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

DESCRIPTION

This is not really meant to be used as a library. It exists to support the sneck script.

CONFIG FORMAT

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

USAGE

snmpd just needs to print the cache. The simplest way is to cat the GZip+BASE64 compressed cache, which avoids starting perl at all.

extend sneck /bin/cat /var/cache/sneck.cache.snmp

sneck -c may be used instead. It reports a missing cache file as error JSON instead of printing nothing, but has to start perl and read the config on each poll.

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

If the cache file is changed via cache_file or -C, cat its .snmp file instead, or give -c the same -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 alert 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 unknown 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.

- $hash{data}{compliance_ok} :: Count of ok compliance checks.

- $hash{data}{compliance_warning} :: Count of warning compliance checks.

- $hash{data}{compliance_critical} :: Count of critical compliance checks.

- $hash{data}{compliance_unknown} :: Count of unknown compliance checks.

- $hash{data}{compliance_errored} :: Count of errored compliance checks.

- $hash{data}{compliance_waived} :: Count of compliance checks that were not ok but are waived. These are not counted anywhere else.

- $hash{data}{compliance_alert} :: 0/1 for if any compliance check is not ok and not waived. Only sets alert as well if the compliance_alert option is set.

- $hash{data}{compliance_alertString} :: The outputs of compliance checks that are warning, critical, or unknown and not waived. Each is prefixed with the control, or the name if there is none, and the severity, such as '[CIS-5.2.10 high] '. Added to alertString if the compliance_alert option is set.

- $hash{data}{compliance_score} :: Percent of compliance checks that are ok, leaving out waived ones, to two decimal places. undef if there are none to score.

- $hash{data}{compliance_frameworks}{$framework} :: The same counts as above for compliance checks with that framework, as ok, warning, critical, unknown, errored, waived, and score.

- $hash{data}{compliance_state_error} :: Only present if the compliance state file could not be read or written. Compliance checks are run 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 or timed out, this is -1. For a perl check, -1 is it not being able to be loaded and timing out is 3, see PERL CHECKS in Monitoring::Sneck::Config.

- $hash{data}{checks}{$name}{error} :: Only present if it died on a signal, timed out, 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. Debug checks are run the same as checks, including check_timeout, check_timeout_signal, and check_kill_sub_pids.

- $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 if it died on a signal, timed out, 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 compliance check in question. They are run the same as checks, except timeout may override check_timeout. See COMPLIANCE in Monitoring::Sneck::Config.

- $hash{data}{compliance}{$name}{check}, ran, output, exit, error, run_time :: The same as for checks. For a cached result, these are from when it last ran.

- $hash{data}{compliance}{$name}{last_ran} :: Time since epoch of when it last started running.

- $hash{data}{compliance}{$name}{cached} :: 0/1 for if this is a earlier result reused because of interval.

- $hash{data}{compliance}{$name}{waived} :: 0/1 for if it is not ok and counted as waived. Errored is never waived.

- $hash{data}{compliance}{$name}{control}, framework, severity, waived_until, waiver :: Only present if set in the config.

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.

- $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 and its checks still met the threshold afterwards, unless one of the above already set it.

- $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

'compliance_state_file' is where compliance check state, used for interval, is kept. It is only read or written if a compliance check has a interval. Default :: /var/cache/sneck.cache.compliance

'check_timeout', 'check_timeout_signal', and 'check_kill_sub_pids' override the options of the same names in the config. See OPTIONS in Monitoring::Sneck::Config. 'check_timeout_signal' may also be 'none' to send no signal even if the config sets one. Bad values are reported the same as config errors.

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:

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)