.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" 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 "Monitoring::Livestatus 3pm"
.TH Monitoring::Livestatus 3pm "2011-04-22" "perl v5.12.3" "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"
Monitoring::Livestatus \- Perl API for check_mk livestatus to access runtime
data from Nagios and Icinga
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&    use Monitoring::Livestatus;
\&    my $ml = Monitoring::Livestatus\->new(
\&      socket => \*(Aq/var/lib/livestatus/livestatus.sock\*(Aq
\&    );
\&    my $hosts = $ml\->selectall_arrayref("GET hosts");
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module connects via socket/tcp to the check_mk livestatus addon for Nagios
and Icinga. You first have to install and activate the mklivestatus addon in your
monitoring installation.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.SS "new ( [\s-1ARGS\s0] )"
.IX Subsection "new ( [ARGS] )"
Creates an \f(CW\*(C`Monitoring::Livestatus\*(C'\fR object. \f(CW\*(C`new\*(C'\fR takes at least the
socketpath.  Arguments are in key-value pairs.
See \s-1EXAMPLES\s0 for more complex variants.
.IP "socket" 4
.IX Item "socket"
path to the \s-1UNIX\s0 socket of check_mk livestatus
.IP "server" 4
.IX Item "server"
use this server for a \s-1TCP\s0 connection
.IP "peer" 4
.IX Item "peer"
alternative way to set socket or server, if value contains ':' server is used,
else socket
.IP "name" 4
.IX Item "name"
human readable name for this connection, defaults to the the socket/server
address
.IP "verbose" 4
.IX Item "verbose"
verbose mode
.IP "line_seperator" 4
.IX Item "line_seperator"
ascii code of the line seperator, defaults to 10, (newline)
.IP "column_seperator" 4
.IX Item "column_seperator"
ascii code of the column seperator, defaults to 0 (null byte)
.IP "list_seperator" 4
.IX Item "list_seperator"
ascii code of the list seperator, defaults to 44 (comma)
.IP "host_service_seperator" 4
.IX Item "host_service_seperator"
ascii code of the host/service seperator, defaults to 124 (pipe)
.IP "keepalive" 4
.IX Item "keepalive"
enable keepalive. Default is off
.IP "errors_are_fatal" 4
.IX Item "errors_are_fatal"
errors will die with an error message. Default: on
.IP "warnings" 4
.IX Item "warnings"
show warnings
currently only querys without Columns: Header will result in a warning
.IP "timeout" 4
.IX Item "timeout"
set a general timeout. Used for connect and querys, no default
.IP "query_timeout" 4
.IX Item "query_timeout"
set a query timeout. Used for retrieving querys, Default 60sec
.IP "connect_timeout" 4
.IX Item "connect_timeout"
set a connect timeout. Used for initial connections, default 5sec
.IP "use_threads" 4
.IX Item "use_threads"
only used with multiple backend connections.
Default is to don't threads where available. As threads in perl
are causing problems with tied resultset and using more memory.
Querys are usually faster without threads, except for very slow backends
connections.
.PP
If the constructor is only passed a single argument, it is assumed to
be a the \f(CW\*(C`peer\*(C'\fR specification. Use either socker \s-1OR\s0 server.
.SH "METHODS"
.IX Header "METHODS"
.SS "do"
.IX Subsection "do"
.Vb 2
\& do($statement)
\& do($statement, %opts)
.Ve
.PP
Send a single statement without fetching the result.
Always returns true.
.SS "selectall_arrayref"
.IX Subsection "selectall_arrayref"
.Vb 3
\& selectall_arrayref($statement)
\& selectall_arrayref($statement, %opts)
\& selectall_arrayref($statement, %opts, $limit )
.Ve
.PP
Sends a query and returns an array reference of arrays
.PP
.Vb 1
\&    my $arr_refs = $ml\->selectall_arrayref("GET hosts");
.Ve
.PP
to get an array of hash references do something like
.PP
.Vb 3
\&    my $hash_refs = $ml\->selectall_arrayref(
\&      "GET hosts", { Slice => {} }
\&    );
.Ve
.PP
to get an array of hash references from the first 2 returned rows only
.PP
.Vb 3
\&    my $hash_refs = $ml\->selectall_arrayref(
\&      "GET hosts", { Slice => {} }, 2
\&    );
.Ve
.PP
use limit to limit the result to this number of rows
.PP
column aliases can be defined with a rename hash
.PP
.Vb 8
\&    my $hash_refs = $ml\->selectall_arrayref(
\&      "GET hosts", {
\&        Slice => {},
\&        rename => {
\&          \*(Aqname\*(Aq => \*(Aqhost_name\*(Aq
\&        }
\&      }
\&    );
.Ve
.SS "selectall_hashref"
.IX Subsection "selectall_hashref"
.Vb 2
\& selectall_hashref($statement, $key_field)
\& selectall_hashref($statement, $key_field, %opts)
.Ve
.PP
Sends a query and returns a hashref with the given key
.PP
.Vb 1
\&    my $hashrefs = $ml\->selectall_hashref("GET hosts", "name");
.Ve
.SS "selectcol_arrayref"
.IX Subsection "selectcol_arrayref"
.Vb 2
\& selectcol_arrayref($statement)
\& selectcol_arrayref($statement, %opt )
.Ve
.PP
Sends a query an returns an arrayref for the first columns
.PP
.Vb 1
\&    my $array_ref = $ml\->selectcol_arrayref("GET hosts\enColumns: name");
\&
\&    $VAR1 = [
\&              \*(Aqlocalhost\*(Aq,
\&              \*(Aqgateway\*(Aq,
\&            ];
.Ve
.PP
returns an empty array if nothing was found
.PP
to get a different column use this
.PP
.Vb 4
\&    my $array_ref = $ml\->selectcol_arrayref(
\&       "GET hosts\enColumns: name contacts",
\&       { Columns => [2] }
\&    );
\&
\& you can link 2 columns in a hash result set
\&
\&    my %hash = @{
\&      $ml\->selectcol_arrayref(
\&        "GET hosts\enColumns: name contacts",
\&        { Columns => [1,2] }
\&      )
\&    };
.Ve
.PP
produces a hash with host the contact assosiation
.PP
.Vb 4
\&    $VAR1 = {
\&              \*(Aqlocalhost\*(Aq => \*(Aquser1\*(Aq,
\&              \*(Aqgateway\*(Aq   => \*(Aquser2\*(Aq
\&            };
.Ve
.SS "selectrow_array"
.IX Subsection "selectrow_array"
.Vb 2
\& selectrow_array($statement)
\& selectrow_array($statement, %opts)
.Ve
.PP
Sends a query and returns an array for the first row
.PP
.Vb 1
\&    my @array = $ml\->selectrow_array("GET hosts");
.Ve
.PP
returns undef if nothing was found
.SS "selectrow_arrayref"
.IX Subsection "selectrow_arrayref"
.Vb 2
\& selectrow_arrayref($statement)
\& selectrow_arrayref($statement, %opts)
.Ve
.PP
Sends a query and returns an array reference for the first row
.PP
.Vb 1
\&    my $arrayref = $ml\->selectrow_arrayref("GET hosts");
.Ve
.PP
returns undef if nothing was found
.SS "selectrow_hashref"
.IX Subsection "selectrow_hashref"
.Vb 2
\& selectrow_hashref($statement)
\& selectrow_hashref($statement, %opt)
.Ve
.PP
Sends a query and returns a hash reference for the first row
.PP
.Vb 1
\&    my $hashref = $ml\->selectrow_hashref("GET hosts");
.Ve
.PP
returns undef if nothing was found
.SS "selectscalar_value"
.IX Subsection "selectscalar_value"
.Vb 2
\& selectscalar_value($statement)
\& selectscalar_value($statement, %opt)
.Ve
.PP
Sends a query and returns a single scalar
.PP
.Vb 1
\&    my $count = $ml\->selectscalar_value("GET hosts\enStats: state = 0");
.Ve
.PP
returns undef if nothing was found
.SS "errors_are_fatal"
.IX Subsection "errors_are_fatal"
.Vb 2
\& errors_are_fatal()
\& errors_are_fatal($value)
.Ve
.PP
Enable or disable fatal errors. When enabled the module will croak on any error.
.PP
returns the current setting if called without new value
.SS "warnings"
.IX Subsection "warnings"
.Vb 2
\& warnings()
\& warnings($value)
.Ve
.PP
Enable or disable warnings. When enabled the module will carp on warnings.
.PP
returns the current setting if called without new value
.SS "verbose"
.IX Subsection "verbose"
.Vb 2
\& verbose()
\& verbose($values)
.Ve
.PP
Enable or disable verbose output. When enabled the module will dump out debug output
.PP
returns the current setting if called without new value
.SS "peer_addr"
.IX Subsection "peer_addr"
.Vb 1
\& $ml\->peer_addr()
.Ve
.PP
returns the current peer address
.PP
when using multiple backends, a list of all addresses is returned in list context
.SS "peer_name"
.IX Subsection "peer_name"
.Vb 2
\& $ml\->peer_name()
\& $ml\->peer_name($string)
.Ve
.PP
if new value is set, name is set to this value
.PP
always returns the current peer name
.PP
when using multiple backends, a list of all names is returned in list context
.SS "peer_key"
.IX Subsection "peer_key"
.Vb 1
\& $ml\->peer_key()
.Ve
.PP
returns a uniq key for this peer
.PP
when using multiple backends, a list of all keys is returned in list context
.SS "marked_bad"
.IX Subsection "marked_bad"
.Vb 1
\& $ml\->marked_bad()
.Ve
.PP
returns true if the current connection is marked down
.SS "disable"
.IX Subsection "disable"
.Vb 1
\& $ml\->disable()
.Ve
.PP
disables this connection, returns the last state.
.SS "enable"
.IX Subsection "enable"
.Vb 1
\& $ml\->enable()
.Ve
.PP
enables this connection, returns the last state.
.SH "QUERY OPTIONS"
.IX Header "QUERY OPTIONS"
In addition to the normal query syntax from the livestatus addon, it is
possible to set column aliases in various ways.
.SS "AddPeer"
.IX Subsection "AddPeer"
adds the peers name, addr and key to the result set:
.PP
.Vb 5
\& my $hosts = $ml\->selectall_hashref(
\&   "GET hosts\enColumns: name alias state",
\&   "name",
\&   { AddPeer => 1 }
\& );
.Ve
.SS "Backend"
.IX Subsection "Backend"
send the query only to some specific backends. Only
useful when using multiple backends.
.PP
.Vb 4
\& my $hosts = $ml\->selectall_arrayref(
\&   "GET hosts\enColumns: name alias state",
\&   { Backends => [ \*(Aqkey1\*(Aq, \*(Aqkey4\*(Aq ] }
\& );
.Ve
.SS "Columns"
.IX Subsection "Columns"
.Vb 1
\&    only return the given column indexes
\&
\&    my $array_ref = $ml\->selectcol_arrayref(
\&       "GET hosts\enColumns: name contacts",
\&       { Columns => [2] }
\&    );
\&
\&  see L<selectcol_arrayref> for more examples
.Ve
.SS "Deepcopy"
.IX Subsection "Deepcopy"
.Vb 1
\&    deep copy/clone the result set.
\&
\&    Only effective when using multiple backends and threads.
\&    This can be safely turned off if you dont change the
\&    result set.
\&    If you get an error like "Invalid value for shared scalar" error" this
\&    should be turned on.
\&
\&    my $array_ref = $ml\->selectcol_arrayref(
\&       "GET hosts\enColumns: name contacts",
\&       { Deepcopy => 1 }
\&    );
.Ve
.SS "Limit"
.IX Subsection "Limit"
.Vb 2
\&    Just like the Limit: <nr> option from livestatus itself.
\&    In addition you can add a start,length limit.
\&
\&    my $array_ref = $ml\->selectcol_arrayref(
\&       "GET hosts\enColumns: name contacts",
\&       { Limit => "10,20" }
\&    );
\&
\&    This example will return 20 rows starting at row 10. You will
\&    get row 10\-30.
\&
\&    Cannot be combined with a Limit inside the query
\&    because a Limit will be added automatically.
\&
\&    Adding a limit this way will greatly increase performance and
\&    reduce memory usage.
\&
\&    This option is multibackend safe contrary to the "Limit: " part of a statement.
\&    Sending a statement like "GET...Limit: 10" with 3 backends will result in 30 rows.
\&    Using this options, you will receive only the first 10 rows.
.Ve
.SS "Rename"
.IX Subsection "Rename"
.Vb 1
\&  see L<COLUMN ALIAS> for detailed explainaton
.Ve
.SS "Slice"
.IX Subsection "Slice"
.Vb 1
\&  see L<selectall_arrayref> for detailed explainaton
.Ve
.SS "Sum"
.IX Subsection "Sum"
The Sum option only applies when using multiple backends.
The values from all backends with be summed up to a total.
.PP
.Vb 4
\& my $stats = $ml\->selectrow_hashref(
\&   "GET hosts\enStats: state = 0\enStats: state = 1",
\&   { Sum => 1 }
\& );
.Ve
.SH "COLUMN ALIAS"
.IX Header "COLUMN ALIAS"
In addition to the normal query syntax from the livestatus addon, it is
possible to set column aliases in various ways.
.PP
A valid Columns: Header could look like this:
.PP
.Vb 3
\& my $hosts = $ml\->selectall_arrayref(
\&   "GET hosts\enColumns: state as status"
\& );
.Ve
.PP
Stats queries could be aliased too:
.PP
.Vb 3
\& my $stats = $ml\->selectall_arrayref(
\&   "GET hosts\enStats: state = 0 as up"
\& );
.Ve
.PP
This syntax is available for: Stats, StatsAnd, StatsOr and StatsGroupBy
.PP
An alternative way to set column aliases is to define rename option key/value
pairs:
.PP
.Vb 5
\& my $hosts = $ml\->selectall_arrayref(
\&   "GET hosts\enColumns: name", {
\&     rename => { \*(Aqname\*(Aq => \*(Aqhostname\*(Aq }
\&   }
\& );
.Ve
.SH "ERROR HANDLING"
.IX Header "ERROR HANDLING"
Errorhandling can be done like this:
.PP
.Vb 9
\&    use Monitoring::Livestatus;
\&    my $ml = Monitoring::Livestatus\->new(
\&      socket => \*(Aq/var/lib/livestatus/livestatus.sock\*(Aq
\&    );
\&    $ml\->errors_are_fatal(0);
\&    my $hosts = $ml\->selectall_arrayref("GET hosts");
\&    if($Monitoring::Livestatus::ErrorCode) {
\&        croak($Monitoring::Livestatus::ErrorMessage);
\&    }
.Ve
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "Multibackend Configuration"
.IX Subsection "Multibackend Configuration"
.Vb 10
\&    use Monitoring::Livestatus;
\&    my $ml = Monitoring::Livestatus\->new(
\&      name       => \*(Aqmultiple connector\*(Aq,
\&      verbose   => 0,
\&      keepalive => 1,
\&      peer      => [
\&            {
\&                name => \*(AqDMZ Monitoring\*(Aq,
\&                peer => \*(Aq50.50.50.50:9999\*(Aq,
\&            },
\&            {
\&                name => \*(AqLocal Monitoring\*(Aq,
\&                peer => \*(Aq/tmp/livestatus.socket\*(Aq,
\&            },
\&            {
\&                name => \*(AqSpecial Monitoring\*(Aq,
\&                peer => \*(Aq100.100.100.100:9999\*(Aq,
\&            }
\&      ],
\&    );
\&    my $hosts = $ml\->selectall_arrayref("GET hosts");
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
For more information about the query syntax and the livestatus plugin installation
see the Livestatus page: http://mathias\-kettner.de/checkmk_livestatus.html
.SH "AUTHOR"
.IX Header "AUTHOR"
Sven Nierlein, <nierlein@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2009 by Sven Nierlein
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.