NAME

Nagios::MKLivestatus - access nagios runtime data from check_mk livestatus Nagios addon

SYNOPSIS

    use Nagios::MKLivestatus;
    my $nl = Nagios::MKLivestatus->new(
      socket => '/var/lib/nagios3/rw/livestatus.sock'
    );
    my $hosts = $nl->selectall_arrayref("GET hosts");

DESCRIPTION

This module connects via socket to the check_mk livestatus nagios addon. You first have to install and activate the livestatus addon in your nagios installation.

CONSTRUCTOR

new ( [ARGS] )

Creates an Nagios::MKLivestatus object. new takes at least the socketpath. Arguments are in key-value pairs. See EXAMPLES for more complex variants.

socket: path to the UNIX socket of check_mk livestatus
server: use this server for a TCP connection
peer: alternative way to set socket or server, if value contains ':' server is used, else socket
name: human readable name for this connection, defaults to the the socket/server address
verbose: verbose mode
line_seperator: ascii code of the line seperator, defaults to 10, (newline)
column_seperator: ascii code of the column seperator, defaults to 0 (null byte)
list_seperator: ascii code of the list seperator, defaults to 44 (comma)
host_service_seperator: ascii code of the host/service seperator, defaults to 124 (pipe)
keepalive: enable keepalive. Default is off
errors_are_fatal: errors will die with an error message. Default: on
warnings: show warnings currently only querys without Columns: Header will result in a warning
timeout: set a general timeout. Used for connect and querys, Default 10sec
use_threads: only used with multiple backend connections. Default is to use threads where available.

If the constructor is only passed a single argument, it is assumed to be a the peer specification. Use either socker OR server.

METHODS

do

 do($statement)
 do($statement, %opts)

Send a single statement without fetching the result. Always returns true.

selectall_arrayref

 selectall_arrayref($statement)
 selectall_arrayref($statement, %opts)
 selectall_arrayref($statement, %opts, $limit )

Sends a query and returns an array reference of arrays

    my $arr_refs = $nl->selectall_arrayref("GET hosts");

to get an array of hash references do something like

    my $hash_refs = $nl->selectall_arrayref(
      "GET hosts", { Slice => {} }
    );

to get an array of hash references from the first 2 returned rows only

    my $hash_refs = $nl->selectall_arrayref(
      "GET hosts", { Slice => {} }, 2
    );

use limit to limit the result to this number of rows

column aliases can be defined with a rename hash

    my $hash_refs = $nl->selectall_arrayref(
      "GET hosts", {
        Slice => {},
        rename => {
          'name' => 'host_name'
        }
      }
    );

selectall_hashref

 selectall_hashref($statement, $key_field)
 selectall_hashref($statement, $key_field, %opts)

Sends a query and returns a hashref with the given key

    my $hashrefs = $nl->selectall_hashref("GET hosts", "name");

selectcol_arrayref

 selectcol_arrayref($statement)
 selectcol_arrayref($statement, %opt )

Sends a query an returns an arrayref for the first columns

    my $array_ref = $nl->selectcol_arrayref("GET hosts\nColumns: name");

    $VAR1 = [
              'localhost',
              'gateway',
            ];

returns an empty array if nothing was found

to get a different column use this

    my $array_ref = $nl->selectcol_arrayref(
       "GET hosts\nColumns: name contacts",
       { Columns => [2] }
    );

 you can link 2 columns in a hash result set

    my %hash = @{
      $nl->selectcol_arrayref(
        "GET hosts\nColumns: name contacts",
        { Columns => [1,2] }
      )
    };

produces a hash with host the contact assosiation

    $VAR1 = {
              'localhost' => 'user1',
              'gateway'   => 'user2'
            };

selectrow_array

 selectrow_array($statement)
 selectrow_array($statement, %opts)

Sends a query and returns an array for the first row

    my @array = $nl->selectrow_array("GET hosts");

returns undef if nothing was found

selectrow_arrayref

 selectrow_arrayref($statement)
 selectrow_arrayref($statement, %opts)

Sends a query and returns an array reference for the first row

    my $arrayref = $nl->selectrow_arrayref("GET hosts");

returns undef if nothing was found

selectrow_hashref

 selectrow_hashref($statement)
 selectrow_hashref($statement, %opt)

Sends a query and returns a hash reference for the first row

    my $hashref = $nl->selectrow_hashref("GET hosts");

returns undef if nothing was found

selectscalar_value

 selectscalar_value($statement)
 selectscalar_value($statement, %opt)

Sends a query and returns a single scalar

    my $count = $nl->selectscalar_value("GET hosts\nStats: state = 0");

returns undef if nothing was found

errors_are_fatal

 errors_are_fatal()
 errors_are_fatal($value)

Enable or disable fatal errors. When enabled the module will croak on any error.

returns the current setting if called without new value

warnings

 warnings()
 warnings($value)

Enable or disable warnings. When enabled the module will carp on warnings.

returns the current setting if called without new value

verbose

 verbose()
 verbose($values)

Enable or disable verbose output. When enabled the module will dump out debug output

returns the current setting if called without new value

peer_addr

 $nl->peer_addr()

returns the current peer address

when using multiple backends, a list of all addresses is returned in list context

peer_name

 $nl->peer_name()
 $nl->peer_name($string)

if new value is set, name is set to this value

always returns the current peer name

when using multiple backends, a list of all names is returned in list context

peer_key

 $nl->peer_key()

returns a uniq key for this peer

when using multiple backends, a list of all keys is returned in list context

marked_bad

 $nl->marked_bad()

returns true if the current connection is marked down

QUERY OPTIONS

In addition to the normal query syntax from the livestatus addon, it is possible to set column aliases in various ways.

AddPeer

adds the peers name, addr and key to the result set:

 my $hosts = $nl->selectall_hashref(
   "GET hosts\nColumns: name alias state",
   "name",
   { AddPeer => 1 }
 );

Backend

send the query only to some specific backends. Only useful when using multiple backends.

 my $hosts = $nl->selectall_arrayref(
   "GET hosts\nColumns: name alias state",
   { Backends => [ 'key1', 'key4' ] }
 );

Columns

    only return the given column indexes

    my $array_ref = $nl->selectcol_arrayref(
       "GET hosts\nColumns: name contacts",
       { Columns => [2] }
    );

  see L<selectcol_arrayref> for more examples

Rename

  see L<COLUMN ALIAS> for detailed explainaton

Slice

  see L<selectall_arrayref> for detailed explainaton

Sum

The Sum option only applies when using multiple backends. The values from all backends with be summed up to a total.

 my $stats = $nl->selectrow_hashref(
   "GET hosts\nStats: state = 0\nStats: state = 1",
   { Sum => 1 }
 );

COLUMN ALIAS

In addition to the normal query syntax from the livestatus addon, it is possible to set column aliases in various ways.

A valid Columns: Header could look like this:

 my $hosts = $nl->selectall_arrayref(
   "GET hosts\nColumns: state as status"
 );

Stats queries could be aliased too:

 my $stats = $nl->selectall_arrayref(
   "GET hosts\nStats: state = 0 as up"
 );

This syntax is available for: Stats, StatsAnd, StatsOr and StatsGroupBy

An alternative way to set column aliases is to define rename option key/value pairs:

 my $hosts = $nl->selectall_arrayref(
   "GET hosts\nColumns: name", {
     rename => { 'name' => 'hostname' }
   }
 );

ERROR HANDLING

Errorhandling can be done like this:

    use Nagios::MKLivestatus;
    my $nl = Nagios::MKLivestatus->new(
      socket => '/var/lib/nagios3/rw/livestatus.sock'
    );
    $nl->errors_are_fatal(0);
    my $hosts = $nl->selectall_arrayref("GET hosts");
    if($Nagios::MKLivestatus::ErrorCode) {
        croak($Nagios::MKLivestatus::ErrorMessage);
    }

EXAMPLES

Multibackend Configuration

    use Nagios::MKLivestatus;
    my $nl = Nagios::MKLivestatus->new(
      name       => 'multiple connector',
      verbose   => 0,
      keepalive => 1,
      peer      => [
            {
                name => 'DMZ Nagios',
                peer => '50.50.50.50:9999',
            },
            {
                name => 'Local Nagios',
                peer => '/tmp/livestatus.socket',
            },
            {
                name => 'Special Nagios',
                peer => '100.100.100.100:9999',
            }
      ],
    );
    my $hosts = $nl->selectall_arrayref("GET hosts");

AUTHOR

Sven Nierlein, <nierlein@cpan.org>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

To install Nagios::MKLivestatus, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Nagios::MKLivestatus

CPAN shell

perl -MCPAN -e shell
install Nagios::MKLivestatus

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

CONSTRUCTOR

new ( [ARGS] )

METHODS

do

selectall_arrayref

selectall_hashref

selectcol_arrayref

selectrow_array

selectrow_arrayref

selectrow_hashref

selectscalar_value

errors_are_fatal

warnings

verbose

peer_addr

peer_name

peer_key

marked_bad

QUERY OPTIONS

AddPeer

Backend

Columns

Rename

Slice

Sum

COLUMN ALIAS

ERROR HANDLING

EXAMPLES

Multibackend Configuration

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions