The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Net-NSCAng-Client-v2.0.1_03
River stage zero No dependents
/ Net::NSCAng::Client

NAME

Net::NSCAng::Client - Submit host and service monitoring results using the NSCA-ng protocol

SYNOPSIS

  use Net::NSCAng::Client ':rcodes';
  my $c = Net::NSCAng::Client->new('icinga.mydomain.org', 'myid', 's3cr3t',
    node_name => 'server_name',
  );
  $c->svc_result(WARNING, 'BogusService is bogus!', { svc_description => 'bogus' });

DESCRIPTION

Net::NSCAng::Client provides a means of submitting host or service check results to an NSCA-ng server, and to remote-control your monitoring system using external commands. It is derived from the Python module written by Alexander Golovko but with a more perlish interface and additional functionality for sending arbitrary external commands.

EXPORT

Nothing by default. The standard Nagios return codes OK, WARNING, CRITICAL, UNKNOWN and DEPENDENT are available. If you don't use something like Monitoring::Plugin that exports the same values, use :rcodes as above to import them. The :all tag is currently synonymous with :rcodes but might export more things in te future.

ERROR HANDLING

None of the methods except for new() return anything useful if they completed successfully. Errors are signalled by dying with an error message, so use eval, Try::Tiny or the like.

METHODS

new

  $o = new($host, $identity, $psk, %tags);
  $o = new("icinga.local", "ID", "s3cr3t", node_name => hostname());

The constructor takes three mandatory positional arguments and a number of optional ones that may be passed as hash-style arguments inline or as a hashref. The mandatory ones:

$host: The host name or IP address of the NSCA-ng server
$identity: An arbitrary identity string that is used by the server to find the corrent PSK. You can think of this as the "user name" part of a regular login.
$psk: A pre-shared key configured on the server for $identity.

The following tags are optional:

port: the TCP port the NSCA-ng server runs on. Defaults to 5668.
ciphers: A list of ciphers for OpenSSL to use. See ciphers(1) for details and don't mess with this unless you know what you're doing. The default is fine.
node_name: The name of the local host as configured in your monitoring system. This is almost always the host name. You may pass this as an argument to any of the result methods, but considering that a single host or service check hardly ever submits results for more than one host, it makes sense to specify this at construction time and not to worry about it later.
svc_description: The service description as configured in your monitoring system. Same rationale as node_name above.
timeout: The timeout in seconds to wait for server responses and connection setup. Default is 10.

svc_result

  svc_result($return_code, $plugin_output, %tags);
  svc_result(WARNING, "Warning: foo is purple!");

Submit a service check result. $return_code is a Nagios-style plugin return code between 0 and 4, and $plugin_output is a human-readable description. The optional arguments may be passed hash-style inline or as a hashref just like for the constructor. The supported keys are node_name and svc_description, see "new()" for their use. If specified here, the values override anything that may have been set in the constructor. If you haven't set them in the constructor, you MUST set them here though!

host_result

  host_result($return_code, $plugin_output, %tags);
  host_result(OK, "Everything is peachy");

Submit a host check result. This is the same as "svc_result()", the only exception being that the svc_description argument obviously makes no sense for a host check and is thus not supported. If an svc_description should have been set in the constructor, it is ignored for this call.

command

  command($cmd);
  command(
    sprintf("SCHEDULE_HOST_DOWNTIME;myserver;%d;%d;1;0;0;root;Hooray for NSCA-ng!",
        0+time, 3600+time
    )
  );

Submit an arbitrary command to your monitoring host. Commands have to be prefixed by a timestamp in seconds since the Unix epoch enclosed in angle brackets to be accepted by the server; if you leave this off, the method will add it for you. Refer to the Nagios/Icinga documentiation for available commands and the format to follow for each command.

BUGS

This module is not thread safe! Due do a workaround for the godawful OpenSSL API, static data has to be used, and this will cause problems with threads. The original Python library uses pthreads to get around that but due to Perl's different threading model this would probably not work. Using the MY_CXT macros is a possibility but frankly I'm too lazy to try just for supporting Perl threads that don't work well in the first place.
I have enabled extra compiler warnings for gcc. This may break things on other compilers and will unfortunately also spew a lot of warnings within Perl header files.

SEE ALSO

send_nsca(8)

AUTHOR

Matthias Bethke, <matthias@towiski.de>

COPYRIGHT AND LICENSE

Copyright (C) 2015 by Matthias Bethke. Portions Copyright (C) by Alexander Golovko <alexandro@onsec.ru>.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.20.2 or, at your option, any later version of Perl 5 you may have available.