NAME

Opsview::RestAPI - Interact with the Opsview Rest API interface

VERSION

version 1.210670

SYNOPSIS

use Opsview::RestAPI;

my $rest=Opsview::RestAPI();
# equivalent to
my $rest=Opsview::RestAPI->new(
    url => 'http://localhost',
    username => 'admin',
    password => 'initial',
);

my %api_version=$rest->api_version;
$rest->login;
my %opsview_info=$rest->opsview_info;
$rest->logout;

DESCRIPTION

Allow for easier access to the Opsview Monitor Rest API, version 4.x and newer. See https://knowledge.opsview.com/reference for more details.

BUILDING AND INSTALLING

This is a Perl module distribution. It should be installed with whichever tool you use to manage your installation of Perl, e.g. any of

cpanm .
cpan  .
cpanp -i .

Consult http://www.cpan.org/modules/INSTALL.html for further instruction.

Should you wish to install this module manually, the procedure is

perl Makefile.PL
make
make test
make install

You can amend where the module will be installed using

perl Makefile.PL LIB=/path/to/perl/lib INSTALLSITEMAN3DIR=/path/to/perl/man/man3

EXAMPLES

Please see the files within the examples and t/ test directory.

METHODS

$rest = Opsview::RestAPI->new();

Create an object using default values for 'url', 'username' and 'password'. Extra options are:

ssl_verify_hostname => 1
debug => 0

$url = $rest->url;

$username = $rest->username;

$password = $rest->password;

Return the settings the object was configured with

$rest->login

Authenticate with the Opsvsiew server using the credentials given in new(). This must be done before any other calls (except api_version) are performed.

$api_version = $rest->api_version

Return a hash reference with details about the Rest API version in the Opsview Monitor instance. May be called without being logged in.

Example hashref:

{
  api_min_version => "2.0",
  api_version     => 5.005005,
  easyxdm_version => "2.4.19",
},

$version = $rest->opsview_info

Return a hash reference contianing some details about the Opsview Monitor instance.

Example hashref:

{
  hosts_limit            => "25",
  opsview_build          => "5.4.0.171741442",
  opsview_edition        => "commercial",
  opsview_version        => "5.4.0",
  server_timezone        => "Europe/London",
  server_timezone_offset => 0,
  uuid                   => "ABCDEF12-ABCD-ABCD-ABCD-ABCDEFABCDEF",
}

$version = $rest->opsview_version

Return a Version Object for the version of Opsview. Implicitly calls opsview_info if required. See version for more details

$build = $rest->opsview_build

Return the build number of the Opsview Monitor instance

$interval = $rest->interval($seconds);

Return the interval to use when setting check_interval or retry_interval. Opsview 4.x used seconds whereas Opsview 5.x uses minutes.

....
check_interval         => $rest->interval(300),
....

will set an interval time of 5 minutes (300 seconds) in both 4.xand 5.x

....
retry_check_interval   => $rest->interval(20),
....

On Opsview 5.x this will set an interval time of 20 seconds On Opsview 4.x this will set an interval time of 1 minute

$result = $rest->get( api => ..., data => { ... }, params => { ... } );

$result = $rest->post( api => ..., data => { ... }, params => { ... } );

$result = $rest->put( api => ..., data => { ... }, params => { ... } );

$result = $rest->delete( api => ..., data => { ... }, params => { ... } );

Method call on the Rest API to interact with Opsview. See the online documentation at https://knowledge.opsview.com/reference for more information.

The endpoint, data and parameters are all specified as a hash passed to the method. See "perldoc_examples" in examples to see them in use.

To create a Host Template called 'AAA', for example:

$rest->put(
  api  => 'config/servicegroup',
  data => { name => 'AAA' },
);

To check if a plugin exists

$result = $rest->get(
  api    => 'config/plugin/exists',
  params => { name => 'check_plugin_name', }
);
if ( $result->{exists} == 1 ) { .... }

To create a user:

$rest->put(
  api  => 'config/contact',
  data => {
  name        => 'userid',
  fullname    => 'User Name',
  password    => $some_secure_password,
  role        => { name => 'View all, change none', },
  enable_tips => 0,
  variables =>
    [ { name => "EMAIL", value => 'email@example.com' }, ],
  },
);

To search for a host called 'MyHost0' and print specific details. Note, some API endpoints will always return an array, no matter how many objects are returned:

$hosts = $rest->get(
  api => 'config/host',
  params => {
    'json_filter' => '{"name":"MyHost0"}',
  }
);
$myhost = $hosts->list->[0];
print "Opsview Host ID: ", $myhost->{id}, $/;
print "Hostgroup: ", $myhost->{hostgroup}->{name}, $/;
print "IP Address: ", $myhost->{ip}, $/;

You can also search for a name like this:

$hosts = $rest->get(
  api => 'config/host',
  params => {
      s.name => 'MyHost0',
  },
);

To search for 'name1 OR name2' use:

$hosts = $rest->get(
  api => 'config/host',
  params => {
      s.name => [ 'name1', 'name2' ],
  },
);

For some objects it may be useful to print out the returned data structure so you can see what can be modified. Using the ID of the above host:

use Data::Dump qw( pp );
$hosts = $rest->get(
  api => 'config/host/2'
);
$myhost = $hosts->list->[0];
print pp($host); # prints the data structure to STDOUT

The data can then be modified and sent back using 'put' (put updates, post creates):

$myhost->{ip} = '127.10.10.10';
$result = $rest->put(
  api => 'config/host/2',
  data => { %$myhost },
);
print pp($result); # contains full updated host info from Opsview

Be aware that fetching or sending too much data in one go may cause a timeout via the proxy server used with Opsview (Apache2 by default) so processing the data in batches in the client may be required.

get (only) will handle this batching of data for you if you use the option batch_size = <size>> (all other methods ignore this).

$hosts = $rest->get(
  api => 'config/host/2'
  batch_size => 50,
);

The data returned should appear the same as if the following were used:

$hosts = $rest->get(
  api => 'config/host/2'
  params => { rows => 'all' },
);

You canot specify both the 'rows' param and 'batch_size'. All other parameters should be accepted.

$result = $rests->reload();

Make a request to initiate a synchronous reload. An alias to

$rest->post( api => 'reload' );

$result = $rest->reload_pending();

Check to see if there are any pending configuration changes that require a reload to be performed

$result = $rest->file_upload( api => ..., local_file => ..., remote_file => ... );

Upload the given file to the server. For a plugin:

$result = $rest->file_upload(
    api => 'config/plugin/upload',
    local_file => "$Bin/check_random",
    remote_file => "check_random",
);

NOTE: This will only upload the plugin; it will not import it. Use the following:

$result = $rest->post(
    api => "config/plugin/import",
    params => {
        filename => 'check_random',
        overwrite  => 1
    },
);

$result = $rest->logout();

Delete the login session held by Opsview Monitor and invalidate the internally stored data structures.

$rest->remove_keys_from_hash($hashref, $arrayref);

AUTHOR

Duncan Ferguson <duncan_j_ferguson@yahoo.co.uk>

COPYRIGHT AND LICENSE

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

duncs/Opsview-RestAPI