1Mon::Client(3)        User Contributed Perl Documentation       Mon::Client(3)
2
3
4

NAME

6       Mon::Client - Methods for interaction with Mon client
7

SYNOPSIS

9           use Mon::Client;
10

DESCRIPTION

12           Mon::Client is used to interact with "mon" clients. It supports
13           a protocol-independent API for retrieving the status of the mon
14           server, and performing certain operations, such as disableing hosts
15           and service checks.
16

METHODS

18       new Creates a new object. A hash can be supplied which sets the default
19           values. An example which contains all of the variables that you can
20           initialize:
21
22               $c = new Mon::Client (
23                   host => "monhost",
24                   port => 2583,
25                   username => "foo",
26                   password => "bar",
27               );
28
29       password (pw)
30           If pw is provided, sets the password. Otherwise, returns the
31           currently set password.
32
33       host (host)
34           If host is provided, sets the mon host. Otherwise, returns the
35           currently set mon host.
36
37       port (portnum)
38           If portnum is provided, sets the mon port number. Otherwise,
39           returns the currently set port number.
40
41       username (user)
42           If user is provided, sets the user login. Otherwise, returns the
43           currently set user login.
44
45       prot
46           If protocol is provided, sets the protocol, specified by a string
47           which is of the form "1.2.3", where "1" is the major revision, "2"
48           is the minor revision, and "3" is the sub-minor revision.  If
49           protocol is not provided, the currently set protocol is returned.
50
51       protid ([protocol])
52           Returns true if client and server protocol match, false otherwise.
53           Implicitly called by connect. If protocol is specified as an
54           integer, supplies that protocol version to the server for
55           verification.
56
57       version
58           Returns the protocol version of the remote server.
59
60       error
61           Returns the error string from set by the last method, or undef if
62           there was no error.
63
64       connected
65           Returns 0 (not connected) or 1 (connected).
66
67       connect (%args)
68           Connects to the server. If host and port have not been set, uses
69           the defaults. Returns undef on error.  If $args{"skip_protid"} is
70           true, skip protocol identification upon connect.
71
72       disconnect
73           Disconnects from the server. Return undef on error.
74
75       login ( %hash )
76           %hash is optional, but if specified, should contain two keys,
77           username and password.
78
79           Performs the "login" command to authenticate the user to the
80           server.  Uses username and password if specified, otherwise uses
81           the username and password previously set by those methods,
82           respectively.
83
84       checkauth ( command )
85           Checks to see if the specified command, as executed by the current
86           user, is authorized by the server, without actually executing the
87           command.  Returns 1 (command is authorized) or 0 (command is not
88           authorized).
89
90       disable_watch ( watch )
91           Disables watch.
92
93       disable_service ( watch, service )
94           Disables a service, as specified by watch and service.
95
96       disable_host ( host )
97           Disables host.
98
99       enable_watch ( watch )
100           Enables watch.
101
102       enable_service ( watch, service )
103           Enables a service as specified by watch and service.
104
105       enable_host ( host )
106           Enables host.
107
108       set ( group, service, var, val )
109           Sets var in group,service to val. Returns undef on error.
110
111       get ( group, service, var )
112           Gets variable var in group,service and returns it, or undef on
113           error.
114
115       quit
116           Logs out of the server. This method should be followed by a call to
117           the disconnect method.
118
119       list_descriptions
120           Returns a hash of service descriptions, indexed by watch and
121           service. For example:
122
123               %desc = $mon->list_descriptions;
124               print "$desc{'watchname'}->{'servicename'}\n";
125
126       list_deps
127           Lists dependency expressions and their components for all services.
128           If there is no dependency for a particular service, then the value
129           will be "NONE".
130
131               %deps = $mon->list_deps;
132               foreach $watch (keys %deps) {
133                   foreach $service (keys %{$deps{$watch}}) {
134                       my $sref = \%{$deps{$watch}->{$service}};
135                       print "expr ($watch,$service) = $sref->{expression}\n";
136                       print "components ($watch,$service) = @{$sref->{components}}\n";
137                   }
138               }
139
140       list_group ( hostgroup )
141           Lists members of hostgroup. Returns an array of each member.
142
143       list_watch
144           Returns an array of all the defined watch groups and services.
145
146               foreach $w ($mon->list_watch) {
147                   print "group=$w->[0] service=$w->[1]\n";
148               }
149
150       list_opstatus ( [group1, service1], ... )
151           Returns a hash of per-service operational statuses, as indexed by
152           watch and service. The list of anonymous arrays is optional, and if
153           is not provided then the status of all groups and services will be
154           queried.
155
156               %s = $mon->list_opstatus;
157               foreach $watch (keys %s) {
158                   foreach $service (keys %{$s{$watch}}) {
159                       foreach $var (keys %{$s{$watch}{$service}}) {
160                           print "$watch $service $var=$s{$watch}{$service}{$var}\n";
161                       }
162                   }
163               }
164
165       list_failures
166           Returns a hash in the same manner as list_opstatus, but only the
167           services which are in a failure state.
168
169       list_successes
170           Returns a hash in the same manner as list_opstatus, but only the
171           services which are in a success state.
172
173       list_disabled
174           Returns a hash of disabled watches, services, and hosts.
175
176               %d = $mon->list_disabled;
177
178               foreach $group (keys %{$d{"hosts"}}) {
179                   foreach $host (keys %{$d{"hosts"}{$group}}) {
180                       print "host $group/$host disabled\n";
181                   }
182               }
183
184               foreach $watch (keys %{$d{"services"}}) {
185                   foreach $service (keys %{$d{"services"}{$watch}}) {
186                       print "service $watch/$service disabled\n";
187                   }
188               }
189
190               for (keys %{$d{"watches"}}) {
191                   print "watch $_ disabled\n";
192               }
193
194       list_alerthist
195           Returns an array of hash references containing the alert history.
196
197               @a = $mon->list_alerthist;
198
199               for (@a) {
200                   print join (" ",
201                       $_->{"type"},
202                       $_->{"watch"},
203                       $_->{"service"},
204                       $_->{"time"},
205                       $_->{"alert"},
206                       $_->{"args"},
207                       $_->{"summary"},
208                       "\n",
209                   );
210               }
211
212       list_dtlog
213           Returns an array of hash references containing the downtime log.
214
215           @a = $mon->list_dtlog
216
217                for (@a) {
218                  print join (" ",
219                      $_->{"timeup"},
220                      $_->{"group"},
221                      $_->{"service"},
222                      $_->{"failtime"},
223                      $_->{"downtime"},
224                      $_->{"interval"},
225                      $_->{"summary"},
226                      "\n",
227                  );
228                }
229
230       list_failurehist
231           Returns an array of hash references containing the failure history.
232
233               @f = $mon->list_failurehist;
234
235               for (@f) {
236                   print join (" ",
237                       $_->{"watch"},
238                       $_->{"service"},
239                       $_->{"time"},
240                       $_->{"summary"},
241                       "\n",
242                   );
243               }
244
245       list_pids
246           Returns an array of hash references containing the list of process
247           IDs of currently active monitors run by the server.
248
249               @p = $mon->list_pids;
250
251               $server = shift @p;
252
253               for (@p) {
254                   print join (" ",
255                       $_->{"watch"},
256                       $_->{"service"},
257                       $_->{"pid"},
258                       "\n",
259                   );
260               }
261
262       list_state
263           Lists the state of the scheduler. Returns a two-element array. The
264           first element of the array is 0 if the scheduler is stopped, and 1
265           if the scheduler is currently running. The second element of the
266           array returned is the string "scheduler running" if the scheduler
267           is currently running, and if the scheduler is stopped, the second
268           element is the time(2) that the scheduler was stopped.
269
270               @s = $mon->list_state;
271
272               if ($s[0] == 0) {
273                   print "scheduler stopped since " . localtime ($s[1]) . "\n";
274               }
275
276       start
277           Starts the scheduler.
278
279       stop
280           Stops the scheduler.
281
282       reset
283           Resets the server.
284
285       reload ( what )
286           Causes the server to reload its configuration. what is an optional
287           argument, and currently the only supported option is auth, which
288           reloads the authorization file.
289
290       term
291           Terminates the server.
292
293       set_maxkeep
294           Sets the maximum number of history entries to store in memory.
295
296       get_maxkeep
297           Returns the maximum number of history entries to store in memory.
298
299       test ( test, group, service [, exitval, period])
300           Schedules a service test to run immediately, or tests an alert for
301           a given period. test must be monitor, alert, startupalert, or
302           upalert. To test alerts, the exitval and period must be supplied.
303           Periods are identified by their label in the mon config file. If
304           there are no period tags, then the actual period string must be
305           used, exactly as it is listed in the config file.
306
307       test_config
308           Tests the syntax of the configuration file. Returns a two-element
309           array. The first element of the array is 0 if the syntax of the
310           config file is invalid, and 1 if the syntax of the config file is
311           OK. The second element of the array returned is the failure
312           message, if the config file has invalid syntax, and the result code
313           if the config file syntax is OK. This function returns undef if it
314           cannot get a connection or a response from the mon server.
315
316           Config file checking stops as soon as an error is found, so you
317           will need to run this command more than once if you have multiple
318           errors in your config file in order to find them all.
319
320               @s = $mon->test_config;
321
322               if ($s[0] == 0) {
323                   print "error in config file:\n" . $s[1] . "\n";
324               }
325
326       ack ( group, service, text )
327           When group/service is in a failure state, acknowledges this with
328           text, and disables all further alerts during this failure period.
329
330       loadstate ( state )
331           Loads state.
332
333       savestate ( state )
334           Saves state.
335
336       servertime
337           Returns the time on the server using the same output as the time(2)
338           system call.
339
340       send_trap ( %vars )
341           Sends a trap to a remote mon server. Here is an example:
342
343               $mon->send_trap (
344                   group           => "remote-group",
345                   service         => "remote-service",
346                   retval          => 1,
347                   opstatus        => "operational status",
348                   summary         => "summary line",
349                   detail          => "multi-line detailed information",
350               );
351
352           retval must be a nonnegative integer.
353
354           opstatus must be one of fail, ok, coldstart, warmstart, linkdown,
355           unknown, timeout,  untested.
356
357           Returns undef on error.
358
359
360
361perl v5.36.0                      2022-07-22                    Mon::Client(3)
Impressum