NAME

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

SYNOPSIS

  use Net::NSCAng::Client ':all';
  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 sending host or service check results to an NSCA-ng server. It is derived from the Python code written by Alexander Golovko <alexandro@onsec.ru> but with a more perlish interface.

EXPORT

Nothing by default. The standard Nagios return codes OK, WARNING, CRITICAL, UNKNOWN and DEPENDENT are available.

METHODS

new($host, $identity, $psk, %tags)

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

The constructor dies with an error message if anything should go wrong, so use eval, Try::Tiny or the like.

svc_result($return_code, $plugin_output, %tags)

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!

Errors are signaled by dying with an error message.

host_result($return_code, $plugin_output, %tags)

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.

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.

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.