NAME

Monitoring::Icinga - An object oriented interface to Icinga

SYNOPSIS

Simple example:

  use Monitoring::Icinga;
  
  my $api = Monitoring::Icinga->new(
      AuthKey => 'ThisIsTheAuthKey'
  );
  
  $api->set_columns('HOST_NAME', 'HOST_OUTPUT', 'HOST_CURRENT_STATE');
  my $hosts = $api->get_hosts(1,2);

This will query the Icinga Web REST API on localhost. $hosts is an array reference containing the information for every host object, which is currently is DOWN (1) or UNREACHABLE (2).

DESCRIPTION

This module implements an object oriented interface to Icinga using its REST API. It is tested with the Icinga Web REST API v1.2 only, so sending commands via PUT is not yet supported (but will be in the future).

METHODS

new (%config)

Constructor. You can set the following parameters during construction:

  BaseURL             - The URL pointing to the Icinga REST API (default: 'http://localhost/icinga-web/web/api').
  AuthKey             - The Auth key to use (mandatory)
  Target              - 'host' or 'service' (default: 'host')
  Columns             - List (array) of columns to return from API calls
  Filters             - API filter as a hash reference
  ssl_verify_hostname - Verify the SSL hostname. Sets the 'verify_hostname' option of LWP::UserAgent (default: 1)

Example, that returns a hash reference containing some data of all hosts whose state is 1 (that means: WARNING):

  my $api = Monitoring::Icinga->new(
      BaseURL      => 'https://your.icinga.host/icinga-web/web/api',
      AuthKey      => 'ThisIsTheAuthKey',
      Target       => 'host',
      Filters      => {
          'type'  => 'AND',
          'field' => [
              {   
                  'type'   => 'atom',
                  'field'  => [ 'HOST_CURRENT_STATE' ],
                  'method' => [ '=' ],
                  'value'  => [ 1 ],
              },
          ],
      },
      Columns      => [ 'HOST_NAME', 'HOST_OUTPUT', 'HOST_CURRENT_STATE' ],
  );
  
  my $result = $api->call;

You can recall the setters to thange the parameters, filters and columns for later API calls.

set_target ($value)

Set target for API call. Can be 'host' or 'service'. See Icinga Web REST API Documentation at http://docs.icinga.org/latest/en/icinga-web-api.html for details on allowed targets.

set_columns (@array)

Set columns that get returned by a call. The parameters are a list of columns. For a list of valid columns, see the source code of Icinga Web at:

  app/modules/Api/models/Store/LegacyLayer/TargetModifierModel.class.php

Example:

  $api->set_columns('HOST_NAME', 'HOST_CURRENT_STATE', 'HOST_OUTPUT');

set_filters ($hash_reference)

Set filters for API call using a hash reference. See Icinga Web REST API Documentation at http://docs.icinga.org/latest/en/icinga-web-api.html for details on how filters need to be defined. Basically, they define it in JSON syntax, but this module requires a Perl hash reference instead.

Simple Example:

  $api->set_filters( {
      'type'  => 'AND',
      'field' => [
          {   
              'type'   => 'atom',
              'field'  => [ 'HOST_CURRENT_STATE' ],
              'method' => [ '>' ],
              'value'  => [ 0 ],
          },
      ],
  } );

More complex example:

  $api->set_filters( {
      'type' => 'AND',
      'field' => [
          {
              'type' => 'atom',
              'field' => [ 'SERVICE_NAME' ],
              'method' => [ 'like' ],
              'value' => [ '*pop*' ],
          },
          {  
              'type' => 'OR',
              'field' => [
                  {
                      'type' => 'atom',
                      'field' => [ 'SERVICE_CURRENT_STATE' ],
                      'method' => [ '>' ],
                      'value' => [ 0 ],
                  },
                  {   
                      'type' => 'atom',
                      'field' => [ 'SERVICE_IS_FLAPPING' ],
                      'method' => [ '=' ],
                      'value' => [ 1 ],
                  },
              ],
          },
      ],
  };

You don't actually need a filter for the API calls to work. But it is strongly recommended to define one whenever you fetch any data. Otherwise ALL host or service objects will be returned.

By the way: You should filter for host or service objects, not both. Otherwise you will most likely not get the results you want. I.e. if you want to get all hosts and services with problems, you better do two API calls. One for the hosts, another for the services.

get_hosts (@states)

Return an array of all host objects matching the specified states. The parameters can be:

  0 - OK
  1 - DOWN
  2 - UNREACHABLE

You should set the desired columns first, using either the Columns parameter of the constructor or the set_columns() function, i.e.:

  $api->set_columns('HOST_NAME', 'HOST_CURRENT_STATE', 'HOST_OUTPUT');
  $hosts_array = $api->get_hosts(1,2);

That would return the name, state and check output of all hosts in state DOWN or UNREACHABLE.

get_services (@states)

Return an array of all service objects matching the specified states. The parameters can be:

  0 - OK
  1 - WARNING
  2 - CRITICAL
  3 - UNKNOWN

You should set the desired columns first, using either the Columns parameter of the constructor or the set_columns() function, i.e.:

  $api->set_columns('HOST_NAME', 'SERVICE_NAME', 'HOST_CURRENT_STATE', 'HOST_OUTPUT');
  $services_array = $api->get_services(1,2,3);

That would return the host name, service name, state and check output of all services in state WARNING, CRITICAL or UNKNOWN.

call

Do an API call using the current settings (Target, Columns and Filters) and return the complete result as a hash reference. The data you usually want is in $hash->{'result'}.

AUTHOR

Robin Schroeder, <schrorg@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2014 by Robin Schroeder

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10 or, at your option, any later version of Perl 5 you may have available.