Debian Codegraph @

perl/lib/Net/NSCAng/Client.pm

raw
1 package Net::NSCAng::Client;
2
3 use 5.010001;
4 use strict;
5 use warnings;
6 use Carp;
7
8 require Exporter;
9 our @ISA = qw(Exporter);
10
11 our %EXPORT_TAGS = (
12 all => [ qw/ OK WARNING CRITICAL UNKNOWN DEPENDENT / ],
13 rcodes => [ qw/ OK WARNING CRITICAL UNKNOWN DEPENDENT / ],
14 );
15 our @EXPORT_OK = ( @{ $EXPORT_TAGS{all} } );
16
17 use version 0.77; our $VERSION = qv('v2.0.0');
18
19 use constant OK => 0;
20 use constant WARNING => 1;
21 use constant CRITICAL => 2;
22 use constant UNKNOWN => 3;
23 use constant DEPENDENT => 4;
24
25 require XSLoader;
26 XSLoader::load('Net::NSCAng::Client', $VERSION);
27
28 =head1 NAME
29
30 Net::NSCAng::Client - Submit host and service monitoring results using the NSCA-ng protocol
31
32 =head1 SYNOPSIS
33
34 use Net::NSCAng::Client ':rcodes';
35 my $c = Net::NSCAng::Client->new('icinga.mydomain.org', 'myid', 's3cr3t',
36 node_name => 'server_name',
37 );
38 $c->svc_result(WARNING, 'BogusService is bogus!', { svc_description => 'bogus' });
39
40 =head1 DESCRIPTION
41
42 Net::NSCAng::Client provides a means of submitting host or service check
43 results to an L<NSCA-ng|http://www.nsca-ng.org/> server, and to remote-control
44 your monitoring system using L<external commands|http://docs.icinga.org/latest/en/extcommands2.html>.
45 It is derived from the Python module written by Alexander Golovko but with a
46 more perlish interface and additional functionality for sending arbitrary
47 external commands.
48
49 =head2 EXPORT
50
51 Nothing by default. The standard Nagios return codes C<OK>, C<WARNING>,
52 C<CRITICAL>, C<UNKNOWN> and C<DEPENDENT> are available. If you don't use
53 something like L<Monitoring::Plugin> that exports the same values, use
54 C<:rcodes> as above to import them. The C<:all> tag is currently synonymous
55 with C<:rcodes> but might export more things in te future.
56
57 =head1 METHODS
58
59 =head2 new
60
61 $o = new($host, $identity, $psk, %tags);
62 $o = new("icinga.local", "ID", "s3cr3t", node_name => hostname());
63
64 The constructor takes three mandatory positional arguments and a number of
65 optional ones that may be passed as hash-style arguments inline or as a
66 hashref. The mandatory ones:
67
68 =over 4
69
70 =item C<$host>: The host name or IP address of the NSCA-ng server
71
72 =item C<$identity>: An arbitrary identity string that is used by the server to
73 find the corrent PSK. You can think of this as the "user name" part of a
74 regular login.
75
76 =item C<$psk>: A pre-shared key configured on the server for C<$identity>.
77
78 =back
79
80 The following tags are optional:
81
82 =over 4
83
84 =item C<port>: the TCP port the NSCA-ng server runs on. Defaults to 5668.
85
86 =item C<ciphers>: A list of ciphers for OpenSSL to use. See ciphers(1) for
87 details and don't mess with this unless you know what you're doing. The default
88 is fine.
89
90 =item C<node_name>: The name of the local host as configured in your monitoring
91 system. This is almost always the host name. You may pass this as an argument
92 to any of the result methods, but considering that a single host or service
93 check hardly ever submits results for more than one host, it makes sense to
94 specify this at construction time and not to worry about it later.
95
96 =item C<svc_description>: The service description as configured in your
97 monitoring system. Same rationale as C<node_name> above.
98
99 =item C<timeout>: The timeout in seconds to wait for server responses and
100 connection setup. Default is 10.
101
102 =back
103
104 The constructor dies with an error message if anything should go wrong, so use
105 C<eval>, L<Try::Tiny> or the like.
106
107 =cut
108
109 sub new {
110 my ($class, $host, $identity, $psk) = splice(@_, 0, 4);
111 my %args = @_%2 ? %{$_[0]} : @_;
112 $class->_new($host, $args{port} // 5668, $identity, $psk,
113 @args{qw/ ciphers node_name svc_description /},
114 $args{timeout} // 10,
115 );
116 }
117
118 =head2 svc_result
119
120 svc_result($return_code, $plugin_output, %tags);
121 svc_result(WARNING, "Warning: foo is purple!");
122
123 Submit a service check result. C<$return_code> is a Nagios-style plugin return
124 code between 0 and 4, and C<$plugin_output> is a human-readable description.
125 The optional arguments may be passed hash-style inline or as a hashref just
126 like for the constructor. The supported keys are C<node_name> and
127 C<svc_description>, see L</new()> for their use. If specified here, the values
128 override anything that may have been set in the constructor. If you haven't set
129 them in the constructor, you MUST set them here though!
130
131 Errors are signaled by dying with an error message.
132
133 =cut
134
135 sub svc_result {
136 my ($self, $return_code, $plugin_output) = splice(@_, 0, 3);
137 my %args = @_%2 ? %{$_[0]} : @_;
138 my $err = $self->_result(0,
139 @args{qw/ node_name svc_description /}, $return_code, $plugin_output
140 );
141 $err and croak("svc_result: $err");
142 }
143
144 =head2 host_result
145
146 host_result($return_code, $plugin_output, %tags);
147 host_result(OK, "Everything is peachy");
148
149 Submit a host check result. This is the same as L</svc_result()>, the only
150 exception being that the C<svc_description> argument obviously makes no sense
151 for a host check and is thus not supported. If an C<svc_description> should
152 have been set in the constructor, it is ignored for this call.
153
154 =cut
155
156 sub host_result {
157 my ($self, $return_code, $plugin_output) = splice(@_, 0, 3);
158 my %args = @_%2 ? %{$_[0]} : @_;
159 my $err = $self->_result(1, $args{node_name}, '', $return_code, $plugin_output);
160 $err and croak("host_result: $err");
161 }
162
163 =head2 command
164
165 command($cmd);
166 command(
167 sprintf("SCHEDULE_HOST_DOWNTIME;myserver;%d;%d;1;0;0;root;Hooray for NSCA-ng!",
168 0+time, 3600+time
169 )
170 );
171
172 Submit an arbitrary command to your monitoring host. Commands have to be
173 prefixed by a timestamp in seconds since the Unix epoch enclosed in angle
174 brackets to be accepted by the server; if you leave this off, the method will
175 add it for you. Refer to the Nagios/Icinga documentiation for available
176 commands and the format to follow for each command.
177
178 =cut
179
180 1;
181 __END__
182
183 =head1 BUGS
184
185 This module is not thread safe! Due do a workaround for the godawful OpenSSL
186 API, static data has to be used, and this I<will> cause problems with threads.
187 The original Python library uses pthreads to get around that but due to Perl's
188 different threading model this would probably not work. Using the C<MY_CXT>
189 macros is a possibility but frankly I'm too lazy to try just for supporting
190 Perl threads that don't work well in the first place.
191
192 =head1 SEE ALSO
193
194 L<send_nsca(8)>
195
196 =head1 AUTHOR
197
198 Matthias Bethke, E<lt>[email protected]<gt>
199
200 =head1 COPYRIGHT AND LICENSE
201
202 Copyright (C) 2015 by Matthias Bethke.
203 Portions Copyright (C) by Alexander Golovko <[email protected]>.
204
205 This library is free software; you can redistribute it and/or modify
206 it under the same terms as Perl itself, either Perl version 5.20.2 or,
207 at your option, any later version of Perl 5 you may have available.
208
209 =cut