1Mon::Client(3) User Contributed Perl Documentation Mon::Client(3)
2
6 Mon::Client - Methods for interaction with Mon client
7
9 use Mon::Client;
10
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
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 $c = new Mon::Client (
23 host => "monhost",
24 port => 2583,
25 username => "foo",
26 password => "bar",
27 );
28 password (pw)
30 If pw is provided, sets the password. Otherwise, returns the
31 currently set password.
32 host (host)
34 If host is provided, sets the mon host. Otherwise, returns the
35 currently set mon host.
36 port (portnum)
38 If portnum is provided, sets the mon port number. Otherwise,
39 returns the currently set port number.
40 username (user)
42 If user is provided, sets the user login. Otherwise, returns the
43 currently set user login.
44 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 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 version
58 Returns the protocol version of the remote server.
59 error
61 Returns the error string from set by the last method, or undef if
62 there was no error.
63 connected
65 Returns 0 (not connected) or 1 (connected).
66 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 disconnect
73 Disconnects from the server. Return undef on error.
74 login ( %hash )
76 %hash is optional, but if specified, should contain two keys,
77 username and password.
78 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 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 disable_watch ( watch )
91 Disables watch.
92 disable_service ( watch, service )
94 Disables a service, as specified by watch and service.
95 disable_host ( host )
97 Disables host.
98 enable_watch ( watch )
100 Enables watch.
101 enable_service ( watch, service )
103 Enables a service as specified by watch and service.
104 enable_host ( host )
106 Enables host.
107 set ( group, service, var, val )
109 Sets var in group,service to val. Returns undef on error.
110 get ( group, service, var )
112 Gets variable var in group,service and returns it, or undef on
113 error.
114 quit
116 Logs out of the server. This method should be followed by a call to
117 the disconnect method.
118 list_descriptions
120 Returns a hash of service descriptions, indexed by watch and
121 service. For example:
122 %desc = $mon->list_descriptions;
124 print "$desc{'watchname'}->{'servicename'}\n";
125 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 %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 list_group ( hostgroup )
141 Lists members of hostgroup. Returns an array of each member.
142 list_watch
144 Returns an array of all the defined watch groups and services.
145 foreach $w ($mon->list_watch) {
147 print "group=$w->[0] service=$w->[1]\n";
148 }
149 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 %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 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 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 list_disabled
174 Returns a hash of disabled watches, services, and hosts.
175 %d = $mon->list_disabled;
177 foreach $group (keys %{$d{"hosts"}}) {
179 foreach $host (keys %{$d{"hosts"}{$group}}) {
180 print "host $group/$host disabled\n";
181 }
182 }
183 foreach $watch (keys %{$d{"services"}}) {
185 foreach $service (keys %{$d{"services"}{$watch}}) {
186 print "service $watch/$service disabled\n";
187 }
188 }
189 for (keys %{$d{"watches"}}) {
191 print "watch $_ disabled\n";
192 }
193 list_alerthist
195 Returns an array of hash references containing the alert history.
196 @a = $mon->list_alerthist;
198 for (@a) {
200 print join (" ",
201 $_->{"type"},
202 $_->{"watch"},
203 $_->{"service"},
204 $_->{"time"},
205 $_->{"alert"},
206 $_->{"args"},
207 $_->{"summary"},
208 "\n",
209 );
210 }
211 list_dtlog
213 Returns an array of hash references containing the downtime log.
214 @a = $mon->list_dtlog
216 for (@a) {
218 print join (" ",
219 $_->{"timeup"},
220 $_->{"group"},
221 $_->{"service"},
222 $_->{"failtime"},
223 $_->{"downtime"},
224 $_->{"interval"},
225 $_->{"summary"},
226 "\n",
227 );
228 }
229 list_failurehist
231 Returns an array of hash references containing the failure history.
232 @f = $mon->list_failurehist;
234 for (@f) {
236 print join (" ",
237 $_->{"watch"},
238 $_->{"service"},
239 $_->{"time"},
240 $_->{"summary"},
241 "\n",
242 );
243 }
244 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 @p = $mon->list_pids;
250 $server = shift @p;
252 for (@p) {
254 print join (" ",
255 $_->{"watch"},
256 $_->{"service"},
257 $_->{"pid"},
258 "\n",
259 );
260 }
261 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 @s = $mon->list_state;
271 if ($s[0] == 0) {
273 print "scheduler stopped since " . localtime ($s[1]) . "\n";
274 }
275 start
277 Starts the scheduler.
278 stop
280 Stops the scheduler.
281 reset
283 Resets the server.
284 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 term
291 Terminates the server.
292 set_maxkeep
294 Sets the maximum number of history entries to store in memory.
295 get_maxkeep
297 Returns the maximum number of history entries to store in memory.
298 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 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 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 @s = $mon->test_config;
321 if ($s[0] == 0) {
323 print "error in config file:\n" . $s[1] . "\n";
324 }
325 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 loadstate ( state )
331 Loads state.
332 savestate ( state )
334 Saves state.
335 servertime
337 Returns the time on the server using the same output as the time(2)
338 system call.
339 send_trap ( %vars )
341 Sends a trap to a remote mon server. Here is an example:
342 $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 retval must be a nonnegative integer.
353 opstatus must be one of fail, ok, coldstart, warmstart, linkdown,
355 unknown, timeout, untested.
356 Returns undef on error.
358perl v5.34.0 2021-07-22 Mon::Client(3)