The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Monitoring-Sneck-0.5.0
River stage zero No dependents
++
/ Monitoring::Sneck

NAME

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

VERSION

Version 0.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

White space is always cleared from the start of lines via /^[\t ]*/ for each file line that is read in.

Blank lines are ignored.

Lines starting with /\#/ are comments lines.

Lines matching /^[Ee][Nn][Vv]\ [A-Za-z0-9\_]+\=/ are variables. Anything before the the /\=/ is used as the name with everything after being the value.

Lines matching /^[A-Za-z0-9\_]+\=/ are variables. Anything before the the /\=/ is used as the name with everything after being the value.

Lines matching /^[A-Za-z0-9\_]+\|/ are checks to run. Anything before the /\|/ is the name with everything after command to run.

Any other sort of lines are considered an error.

Variables in the checks are in the form of /%+varaible_name%+/.

Variable names and check names may not be redefined once defined in the config.

EXAMPLE CONFIG

    env PATH=/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin
    # this is a comment
    GEOM_DEV=foo
    geom_foo|/usr/local/libexec/nagios/check_geom mirror %GEOM_DEV%
    does_not_exist|/bin/this_will_error yup... that it will
    
    does_not_exist_2|/usr/bin/env /bin/this_will_also_error

The first line sets the %ENV variable PATH.

The second is ignored as it is a comment.

The third sets the variable GEOM_DEV to 'foo'

The fourth creates a check named geom_foo that calls check_geom_mirror with the variable supplied to it being the value specified by the variable GEOM_DEV.

The fith is a example of an error that will show what will happen when you call to a file that does not exit.

The sixth line will be ignored as it is blank.

The seventh is a example of another command erroring.

When you run it, you will notice that errors for lines 4 and 5 are printed to STDERR. For this reason you should use '2> /dev/null' when calling it from snmpd or '2> /dev/null > /dev/null' when calling from cron.

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}{time} :: The hostname the check was ran on.
    
    - $hash{data}{config} :: The raw config file if told to include it.

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.
    
    - $hash{data}{checks}{$name}{error} :: Only present it died on a
      signal or could not be executed. Provides a brief description.

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).

    my $sneck;
    eval{
        $sneck=Monitoring::Sneck->new({config=>$file}, include=>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)