.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Mon::Config 3pm"
.TH Mon::Config 3pm "2012-04-27" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mon::Client \- Methods for interaction with Mon client
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Mon::Client;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.Vb 4
\&    Mon::Client is used to interact with "mon" clients. It supports
\&    a protocol\-independent API for retrieving the status of the mon
\&    server, and performing certain operations, such as disableing hosts
\&    and service checks.
.Ve
.SH "METHODS"
.IX Header "METHODS"
.IP "new" 4
.IX Item "new"
Creates a new object. A hash can be supplied which sets the
default values. An example which contains all of the variables
that you can initialize:
.Sp
.Vb 6
\&    $c = new Mon::Client (
\&        host => "monhost",
\&        port => 2583,
\&        username => "foo",
\&        password => "bar",
\&    );
.Ve
.IP "password (pw)" 4
.IX Item "password (pw)"
If \fIpw\fR is provided, sets the password. Otherwise, returns the
currently set password.
.IP "host (host)" 4
.IX Item "host (host)"
If \fIhost\fR is provided, sets the mon host. Otherwise, returns the
currently set mon host.
.IP "port (portnum)" 4
.IX Item "port (portnum)"
If \fIportnum\fR is provided, sets the mon port number. Otherwise, returns the
currently set port number.
.IP "username (user)" 4
.IX Item "username (user)"
If \fIuser\fR is provided, sets the user login. Otherwise, returns the
currently set user login.
.IP "prot" 4
.IX Item "prot"
If \fIprotocol\fR is provided, sets the protocol, specified by a string
which is of the form \*(L"1.2.3\*(R", where \*(L"1\*(R" is the major revision, \*(L"2\*(R" is
the minor revision, and \*(L"3\*(R" is the sub-minor revision.
If \fIprotocol\fR is not provided, the currently set protocol is returned.
.IP "protid ([protocol])" 4
.IX Item "protid ([protocol])"
Returns true if client and server protocol match, false otherwise.
Implicitly called by \fBconnect\fR. If protocol is specified as an integer,
supplies that protocol version to the server for verification.
.IP "version" 4
.IX Item "version"
Returns the protocol version of the remote server.
.IP "error" 4
.IX Item "error"
Returns the error string from set by the last method, or undef if
there was no error.
.IP "connected" 4
.IX Item "connected"
Returns 0 (not connected) or 1 (connected).
.IP "connect (%args)" 4
.IX Item "connect (%args)"
Connects to the server. If \fBhost\fR and \fBport\fR have not been set,
uses the defaults. Returns \fIundef\fR on error.  If \f(CW$args\fR{\*(L"skip_protid\*(R"}
is true, skip protocol identification upon connect.
.IP "disconnect" 4
.IX Item "disconnect"
Disconnects from the server. Return \fIundef\fR on error.
.ie n .IP "login ( %hash )" 4
.el .IP "login ( \f(CW%hash\fR )" 4
.IX Item "login ( %hash )"
\&\fB\f(CB%hash\fB\fR is optional, but if specified, should contain two keys,
\&\fBusername\fR and \fBpassword\fR.
.Sp
Performs the \*(L"login\*(R" command to authenticate the user to the server.
Uses \fBusername\fR and \fBpassword\fR if specified, otherwise uses
the username and password previously set by those methods, respectively.
.IP "checkauth ( command )" 4
.IX Item "checkauth ( command )"
Checks to see if the specified command, as executed by the current user,
is authorized by the server, without actually executing the command.
Returns 1 (command is authorized) or 0 (command is not authorized).
.IP "disable_watch ( watch )" 4
.IX Item "disable_watch ( watch )"
Disables \fBwatch\fR.
.IP "disable_service ( watch, service )" 4
.IX Item "disable_service ( watch, service )"
Disables a service, as specified by \fBwatch\fR and \fBservice\fR.
.IP "disable_host ( host )" 4
.IX Item "disable_host ( host )"
Disables \fBhost\fR.
.IP "enable_watch ( watch )" 4
.IX Item "enable_watch ( watch )"
Enables \fBwatch\fR.
.IP "enable_service ( watch, service )" 4
.IX Item "enable_service ( watch, service )"
Enables a service as specified by \fBwatch\fR and \fBservice\fR.
.IP "enable_host ( host )" 4
.IX Item "enable_host ( host )"
Enables \fBhost\fR.
.IP "set ( group, service, var, val )" 4
.IX Item "set ( group, service, var, val )"
Sets \fBvar\fR in \fBgroup,service\fR to \fBval\fR. Returns
undef on error.
.IP "get ( group, service, var )" 4
.IX Item "get ( group, service, var )"
Gets variable \fBvar\fR in \fBgroup,service\fR and returns it,
or undef on error.
.IP "quit" 4
.IX Item "quit"
Logs out of the server. This method should be followed
by a call to the \fBdisconnect\fR method.
.IP "list_descriptions" 4
.IX Item "list_descriptions"
Returns a hash of service descriptions, indexed by watch
and service. For example:
.Sp
.Vb 2
\&    %desc = $mon\->list_descriptions;
\&    print "$desc{\*(Aqwatchname\*(Aq}\->{\*(Aqservicename\*(Aq}\en";
.Ve
.IP "list_deps" 4
.IX Item "list_deps"
Lists dependency expressions and their components for all
services. If there is no dependency for a particular service,
then the value will be \*(L"\s-1NONE\s0\*(R".
.Sp
.Vb 8
\&    %deps = $mon\->list_deps;
\&    foreach $watch (keys %deps) {
\&        foreach $service (keys %{$deps{$watch}}) {
\&            my $sref = \e%{$deps{$watch}\->{$service}};
\&            print "expr ($watch,$service) = $sref\->{expression}\en";
\&            print "components ($watch,$service) = @{$sref\->{components}}\en";
\&        }
\&    }
.Ve
.IP "list_group ( hostgroup )" 4
.IX Item "list_group ( hostgroup )"
Lists members of \fBhostgroup\fR. Returns an array of each
member.
.IP "list_watch" 4
.IX Item "list_watch"
Returns an array of all the defined watch groups and services.
.Sp
.Vb 3
\&    foreach $w ($mon\->list_watch) {
\&        print "group=$w\->[0] service=$w\->[1]\en";
\&    }
.Ve
.IP "list_opstatus ( [group1, service1], ... )" 4
.IX Item "list_opstatus ( [group1, service1], ... )"
Returns a hash of per-service operational statuses, as indexed by watch
and service. The list of anonymous arrays is optional, and if is not
provided then the status of all groups and services will be queried.
.Sp
.Vb 8
\&    %s = $mon\->list_opstatus;
\&    foreach $watch (keys %s) {
\&        foreach $service (keys %{$s{$watch}}) {
\&            foreach $var (keys %{$s{$watch}{$service}}) {
\&                print "$watch $service $var=$s{$watch}{$service}{$var}\en";
\&            }
\&        }
\&    }
.Ve
.IP "list_failures" 4
.IX Item "list_failures"
Returns a hash in the same manner as \fBlist_opstatus\fR, but only
the services which are in a failure state.
.IP "list_successes" 4
.IX Item "list_successes"
Returns a hash in the same manner as \fBlist_opstatus\fR, but only
the services which are in a success state.
.IP "list_disabled" 4
.IX Item "list_disabled"
Returns a hash of disabled watches, services, and hosts.
.Sp
.Vb 1
\&    %d = $mon\->list_disabled;
\&
\&    foreach $group (keys %{$d{"hosts"}}) {
\&        foreach $host (keys %{$d{"hosts"}{$group}}) {
\&            print "host $group/$host disabled\en";
\&        }
\&    }
\&
\&    foreach $watch (keys %{$d{"services"}}) {
\&        foreach $service (keys %{$d{"services"}{$watch}}) {
\&            print "service $watch/$service disabled\en";
\&        }
\&    }
\&
\&    for (keys %{$d{"watches"}}) {
\&        print "watch $_ disabled\en";
\&    }
.Ve
.IP "list_alerthist" 4
.IX Item "list_alerthist"
Returns an array of hash references containing the alert history.
.Sp
.Vb 1
\&    @a = $mon\->list_alerthist;
\&
\&    for (@a) {
\&        print join (" ",
\&            $_\->{"type"},
\&            $_\->{"watch"},
\&            $_\->{"service"},
\&            $_\->{"time"},
\&            $_\->{"alert"},
\&            $_\->{"args"},
\&            $_\->{"summary"},
\&            "\en",
\&        );
\&    }
.Ve
.IP "list_dtlog" 4
.IX Item "list_dtlog"
Returns an array of hash references containing the downtime log.
.Sp
\&\f(CW@a\fR = \f(CW$mon\fR\->list_dtlog
.Sp
.Vb 12
\&     for (@a) {
\&       print join (" ",
\&           $_\->{"timeup"},
\&           $_\->{"group"},
\&           $_\->{"service"},
\&           $_\->{"failtime"},
\&           $_\->{"downtime"},
\&           $_\->{"interval"},
\&           $_\->{"summary"},
\&           "\en",
\&       );
\&     }
.Ve
.IP "list_failurehist" 4
.IX Item "list_failurehist"
Returns an array of hash references containing the failure history.
.Sp
.Vb 1
\&    @f = $mon\->list_failurehist;
\&
\&    for (@f) {
\&        print join (" ",
\&            $_\->{"watch"},
\&            $_\->{"service"},
\&            $_\->{"time"},
\&            $_\->{"summary"},
\&            "\en",
\&        );
\&    }
.Ve
.IP "list_pids" 4
.IX Item "list_pids"
Returns an array of hash references containing the list of process IDs
of currently active monitors run by the server.
.Sp
.Vb 1
\&    @p = $mon\->list_pids;
\&
\&    $server = shift @p;
\&
\&    for (@p) {
\&        print join (" ",
\&            $_\->{"watch"},
\&            $_\->{"service"},
\&            $_\->{"pid"},
\&            "\en",
\&        );
\&    }
.Ve
.IP "list_state" 4
.IX Item "list_state"
Lists the state of the scheduler. Returns a two-element array. The 
first element of the array is 0 if the scheduler is stopped, and 1
if the scheduler is currently running. The second element of the array
returned is the string \*(L"scheduler running\*(R" if the scheduler is 
currently running, and if the scheduler is stopped, the second
element is the \fItime\fR\|(2) that the scheduler was stopped.
.Sp
.Vb 1
\&    @s = $mon\->list_state;
\&
\&    if ($s[0] == 0) {
\&        print "scheduler stopped since " . localtime ($s[1]) . "\en";
\&    }
.Ve
.IP "start" 4
.IX Item "start"
Starts the scheduler.
.IP "stop" 4
.IX Item "stop"
Stops the scheduler.
.IP "reset" 4
.IX Item "reset"
Resets the server.
.IP "reload ( what )" 4
.IX Item "reload ( what )"
Causes the server to reload its configuration. \fBwhat\fR is an optional
argument, and currently the only supported option is \fBauth\fR, which
reloads the authorization file.
.IP "term" 4
.IX Item "term"
Terminates the server.
.IP "set_maxkeep" 4
.IX Item "set_maxkeep"
Sets the maximum number of history entries to store in memory.
.IP "get_maxkeep" 4
.IX Item "get_maxkeep"
Returns the maximum number of history entries to store in memory.
.IP "test ( test, group, service [, exitval, period])" 4
.IX Item "test ( test, group, service [, exitval, period])"
Schedules a service test to run immediately, or tests an alert for a
given period. \fBtest\fR must be \fBmonitor\fR, \fBalert\fR, \fBstartupalert\fR, or
\&\fBupalert\fR. To test alerts, the \fBexitval\fR and \fBperiod\fR must be supplied.
Periods are identified by their label in the mon config file. If there
are no period tags, then the actual period string must be used, exactly
as it is listed in the config file.
.IP "test_config" 4
.IX Item "test_config"
Tests the syntax of the configuration file. Returns a two-element 
array. The first element of the array is 0 if the syntax of the
config file is invalid, and 1 if the syntax of the config file
is \s-1OK\s0. The second element of the array returned is the failure 
message, if the config file has invalid syntax, and the result code
if the config file syntax is \s-1OK\s0. This function returns undef if it
cannot get a connection or a response from the mon server.
.Sp
Config file checking stops as soon as an error is found, so
you will need to run this command more than once if you have multiple
errors in your config file in order to find them all.
.Sp
.Vb 1
\&    @s = $mon\->test_config;
\&
\&    if ($s[0] == 0) {
\&        print "error in config file:\en" . $s[1] . "\en";
\&    }
.Ve
.IP "ack ( group, service, text )" 4
.IX Item "ack ( group, service, text )"
When \fBgroup/service\fR is in a failure state,
acknowledges this with \fBtext\fR, and disables all further
alerts during this failure period.
.IP "loadstate ( state )" 4
.IX Item "loadstate ( state )"
Loads \fBstate\fR.
.IP "savestate ( state )" 4
.IX Item "savestate ( state )"
Saves \fBstate\fR.
.IP "servertime" 4
.IX Item "servertime"
Returns the time on the server using the same output as the
\&\fItime\fR\|(2) system call.
.ie n .IP "send_trap ( %vars )" 4
.el .IP "send_trap ( \f(CW%vars\fR )" 4
.IX Item "send_trap ( %vars )"
Sends a trap to a remote mon server. Here is an example:
.Sp
.Vb 8
\&    $mon\->send_trap (
\&        group           => "remote\-group",
\&        service         => "remote\-service",
\&        retval          => 1,
\&        opstatus        => "fail",
\&        summary         => "hosta hostb hostc",
\&        detail          => "hosta hostb and hostc are unresponsive",
\&    );
.Ve
.Sp
\&\fIretval\fR must be a nonnegative integer.
.Sp
\&\fIopstatus\fR must be one of \fIfail\fR, \fIok\fR, \fIcoldstart\fR, \fIwarmstart\fR,
\&\fIlinkdown\fR, \fIunknown\fR, \fItimeout\fR,  \fIuntested\fR.
.Sp
Returns \fIundef\fR on error.