The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Zabbix2-API-0.013
River stage zero No dependents
1 ++
/ Zabbix2::API

NAME

Zabbix2::API -- Access the JSON-RPC API of a Zabbix server

SYNOPSIS

  use Zabbix2::API;

  my $zabbix = Zabbix2::API->new(server => 'http://example.com/zabbix/api_jsonrpc.php');

  eval { $zabbix->login(user => 'calvin',
                        password => 'hobbes') };

  if ($@) { die 'could not authenticate' };

  my $items = $zabbix->fetch('Item', params => { search => { ... } });

DESCRIPTION

This module is a Moo wrapper around the Zabbix 2.x JSON-RPC API.

For the Zabbix 1.8.x series, see Zabbix::API, which happens to retain some limited degree of usefulness with Zabbix 2.x.

What you need to start hacking is probably the fetch method in Zabbix2::API; be sure to check out also what the various Zabbix2::API::Foo classes do, as this is how you'll be manipulating the objects you have just fetched.

ATTRIBUTES

(read-only string, with predicate)

This attribute is set after a successful login. The value is a valid Zabbix session cookie for all intents and purposes; it will be sent in the "auth" key of each JSON-RPC method call. It is unset after a successful logout.

Interestingly, it is also valid for a regular HTTP "Cookie" header, and you can use this fact to your advantage to send arbitrary HTTP requests to the Zabbix server, allowing you to e.g. fetch graph images with a valid user session.

pull_after_push_mode

(read-write boolean, defaults to a true value)

This attribute controls whether updating operations (calling create or update on Zabbix objects) are immediately followed by an automatic pull on the object, to retrieve server-generated values such as IDs. Disabling this behavior causes write operations to become faster, which is handy for a pure-provisioning workflow.

server

(read-only required string)

This must be set to the API endpoint of the Zabbix server. This is usually an HTTP URL of the form

  http://example.com/zabbix/api_jsonrpc.php

All API requests will be made to this URL.

ua

(read-only LWP::UserAgent instance)

All HTTP requests will be performed by this object. By default, it is a vanilla LWP::UserAgent instance with all attributes at their default value except for the User-Agent string, which is set to "Zabbix API client (libwww-perl)".

user

(read-only string, cannot be initialized in the constructor)

This attribute is set to the current user's username after a successful login, and unset after a successful logout.

METHODS

api_version

  my $version = $zabbix->api_version;

Query the Zabbix server for the API version number and return it.

fetch

  my $things_aref = $zabbix->fetch('SomeClass', params => { ... });

This method fetches objects from the server. The params hashref should contain API method parameters that identify the objects you're trying to fetch, for instance:

  $zabbix->fetch('Item', params => {
      search => { key_ => 'system.uptime' } });

The default value of params is an empty hashref, which should mean "fetch every object of type CLASS". See the Zabbix server API documentation here.

The method delegates a lot of work to the CLASS so that it can be as generic as possible. Any CLASS name in the Zabbix2::API namespace is usable as long as it descends from Zabbix2::API::CRUDE (to be precise, it should implement a number of methods, some of which CRUDE implements, some of which are provided by specialized subclasses provided in the distribution). The string Zabbix2::API:: will be prepended if it is missing.

Returns an arrayref of CLASS instances.

Note that if you pass it parameters that change the return type, such as "countOutput", fetch will be hopelessly confused, as it expects the return value to be an array of object property maps.

fetch_single

  my $thing = $zabbix->fetch_single('SomeClass', params => { ... });

Like fetch, but also checks how many objects the server sent back. If no objects were sent, returns undef. If one object was sent, returns that. If more objects were sent, throws an exception. This helps against malformed queries; Zabbix tends to return all objects of a class when a query contains strange parameters (like "searhc" or "fliter").

login

  $zabbix->login(user => 'me', password => 'mypassword');

Send login information to the Zabbix server and set the auth cookie if the authentication was successful.

logout

  $zabbix->logout;

Terminate the current session.

query

  my $results = $zabbix->query(method => 'item.isreadable',
                               params => { ... });

This method encodes the parameters provided, sends an API request, waits for the server response and decodes it. It will throw an exception if the server sends back an API error message or an HTTP error.

useragent

  my $ua = $zabbix->useragent;

Alternative spelling of the ua accessor.

TIPS AND TRICKS

SSL SUPPORT

LWP::UserAgent supports SSL if you install LWP::Protocol::https. You may need to configure LWP::UserAgent manually, e.g.

  my $zabbix = Zabbix2::API->new(
      ua => LWP::UserAgent->new(
          ssl_opts => { verify_hostname => 0,
                        SSL_verify_mode => 'SSL_VERIFY_NONE' }));

LOGGING

Zabbix2::API uses Log::Any to log outgoing requests and incoming responses.

BUGS AND MISSING FEATURES

The user.logout method has been broken ever since the first Zabbix version that included an API. It may have been fixed since.

Wrapping an API class requires a small but nonzero quantity of tuits which I do not have. Thus not all API classes are wrapped. Patches are welcome.

CHANGES FROM Zabbix::API

THE verbosity ATTRIBUTE

This attribute has been removed in favor of Log::Any-based logging. See also the documentation of Log::Any::Adapter.

THE cache ATTRIBUTE

This feature was never very useful. It has been removed to make the code simpler and (hopefully) less bug-prone.

USAGE OF Moo

Zabbix::API used plain Perl objects, mostly due to constraints that existed on the system for which it was originally written. This version uses Moo, which removes a lot of boilerplate and makes the code clearer.

THE _readonly_properties METHOD

Zabbix 1.8.x used to silently ignore read-only properties sent as part of an update or create operation. However, Zabbix 2.x returns an error if they are provided, even if they have not been changed from the value stored on the server. This means that most subclasses of Zabbix2::API::CRUDE need to implement this method to filter out the list of properties that must be removed before calling update or create.

push VS create/update/exists

In Zabbix::API, you could call $thing->push; and it would magically do things depending on if it thought the thing already existed on the server. This was well-suited to our initial usage, but it proved problematic to maintain and hard to adapt to other workflows.

Zabbix2::API has replaced the push method with explicit create, update and exists methods.

CONTRIBUTING

If you wish to contribute to this project, e.g. by writing a class wrapper or fixing bugs etc., I would appreciate if you wrote the attendant unit tests.

All unit tests in t/ are run against a live Zabbix instance, canonically the one provided by this Docker service.

SEE ALSO

The Zabbix API documentation, at http://www.zabbix.com/documentation/start

LWP::UserAgent

AUTHOR

Fabrice Gabolde <fga@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2011, 2012, 2013, 2014 SFR

This library is free software; you can redistribute it and/or modify it under the terms of the GPLv3.