Access the json-rpc api of a zabbix server
use Zabbix::API;
my $zabbix = Zabbix::API->new(server => 'http://example.com/zabbix/api_jsonrpc.php',
verbosity => 0);
eval { $zabbix->login(user => 'calvin',
password => 'hobbes') };
if ($@) { die 'could not authenticate' };
my $items = $zabbix->fetch('Item', params => { search => { ... } });
This module manages authentication and querying to a Zabbix server via its JSON-RPC interface. (Zabbix v1.8+ is required for \s-1API\s0 usage; prior versions have no JSON-RPC \s-1API\s0 at all.)
What you need to start out is probably the \*(C`fetch\*(C' method in \*(C`Zabbix::API\*(C'; be sure to check out also what the various \*(C`Zabbix::API::Foo\*(C' classes do, as this is how you'll be manipulating the objects you have just fetched.
Finally, there are examples in the \*(C`examples/\*(C' folder (well, at least one) and in the unit tests.
This is the main constructor for the Zabbix::API class. It creates a LWP::UserAgent instance but does not open any connections yet. \*(C`env_proxy\*(C' is passed to the LWP::UserAgent constructor, so if it is set to a true value then the \s-1UA\s0 should follow $http_proxy and others. \*(C`server\*(C' is misleading, as the \s-1URL\s0 expected is actually the whole path to the JSON-RPC page, which usually is \*(C`http://example.com/zabbix/api_jsonrpc.php\*(C'. Returns an instance of the \*(C`Zabbix::API\*(C' class.
Send login information to the Zabbix server and set the auth cookie if the authentication was successful. Due to the current state of flux of the Zabbix \s-1API\s0, this may or may not work depending on your version of Zabbix. \*(C`user.authenticate\*(C' is marked as having been introduced in version 1.8; so is \*(C`user.login\*(C', which deprecates \*(C`authenticate\*(C'. Our method uses \*(C`login\*(C'. Version 1.8.4 is confirmed as working with \*(C`login\*(C'.
Try to log out properly. Unfortunately, the \*(C`user.logout\*(C' method is completely undocumented and does not appear to work at the moment (see the bug report here: https://support.zabbix.com/browse/ZBX-3907 <https://support.zabbix.com/browse/ZBX-3907>). Users of this distribution are advised not to log out at all. They will not be able to log back in until the server has decided their ban period is over (around 30s). Furthermore, another bug in Zabbix (resolved in 1.8.5) prevents successful logins to reset the failed logins counter, which means that after three (possibly non-consecutive) failed logins every failed login triggers the ban period. The test suite logs in and out once per test file. The logout method does not work. There are more than three test files. Do the math :(
Send a JSON-RPC query to the Zabbix server. The \*(C`params\*(C' hashref should contain the method's parameters; query parameters (query \s-1ID\s0, auth cookie, JSON-RPC version, and \s-1HTTP\s0 request headers) are set by the method itself. Return a \*(C`HTTP::Response\*(C' object. If the verbosity is set to 1, will print the \*(C`HTTP::Response\*(C' to \s-1STDOUT\s0. If set to 2, will print the Data::Dumper output of same (it also contains the \*(C`HTTP::Request\*(C' being replied to). If the verbosity is strictly greater than 0, the internal LWP::UserAgent instance will also print \s-1HTTP\s0 request progress.
Wrapper around \*(C`raw_query\*(C' that will return the decoded result data instead.
Query the Zabbix server for the \s-1API\s0 version number and return it.
This method fetches objects from the server. The \s-1PARAMS\s0 hashref should contain \s-1API\s0 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 \s-1PARAMS\s0 is an empty hashref, which should mean \*(L"fetch every object of type \s-1CLASS\s0\*(R". The method delegates a lot of work to the \s-1CLASS\s0 so that it can be as generic as possible. Any \s-1CLASS\s0 name in the \*(C`Zabbix::API\*(C' namespace is usable as long as it descends from \*(C`Zabbix::API::CRUDE\*(C' (to be precise, it should implement a number of methods, some of which \*(C`CRUDE\*(C' implements, some of which are provided by specialized subclasses provided in the distribution). The string \*(C`Zabbix::API::\*(C' will be prepended if it is missing. Returns an arrayref of \s-1CLASS\s0 instances.
Like \*(C`fetch\*(C', but also checks how many objects the server sent back. If no objects were sent, returns \*(C`undef\*(C'. 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 \*(L"searhc\*(R" or \*(L"fliter\*(R").
Accessor for the LWP::UserAgent object that handles \s-1HTTP\s0 queries and responses. Several useful options can be set: timeout, redirects, etc.
Mutator for the verbosity level. Implemented verbosities so far are 0, 1 and 2, where:
does not emit any messages,
prints out the \*(C`LWP::UserAgent\*(C' progress messages and the responses sent by the Zabbix server,
prints out the \*(C`LWP::UserAgent\*(C' progress messages and dumps to stdout (via \*(C`Data::Dumper\*(C') the queries sent to the server and the responses received.
Several attributes are available if you want to dig into the class' internals, through the standard blessed-hash-as-an-instance mechanism. Those are:
A string containing the \s-1URL\s0 to which JSON-RPC queries should be POSTed.
Verbosity level. So far levels 0 to 2 are supported (i.e. do something different).
A string containing the current session's auth cookie, or the empty string if unauthenticated.
Direct access to the LWP::UserAgent initial configuration regarding proxies. Setting this attribute after construction does nothing.
Consider the following:
my $host = $zabbix->fetch('Host', params => ...);
my $same_host = Zabbix::API::Host->new(root => $zabbix, params => same...);
$same_host->push;
is_deeply($host, $same_host); # yup isnt($host, $same_host); # also yup
This means you can change the attribute A in $host and push it, and it will change on the server; then you can change some other attribute B in $same_host and push it, and it will change on the server... and attribute A will be changed back to its old value before you changed it in $host since $host and $same_host are different references to different objects and don't know about each other! Of course this is also true if someone else is fiddling with the hosts directly on the web interface or in any other way.
To work around this, you have to \*(C`pull()\*(C' just before you start changing things.
The distribution doesn't use Moose, because it was written with light dependencies in mind. This is actually a problem in that I do not have the time to write proper accessors to cover all types of manipulations one might expect on, for instance, a graph's items. Hence to push (in the stack sense) a new item into a graph's list of items, you have to use the push builtin on the dereferenced items mutator, instead of writing something like
$graph->items->push($foo);
which would be easy to allow with Moose traits. Plus, I had to write boilerplate validation code, which would have been taken care of by Moose at least where types and type coercions are concerned.
It is quite slow. The server itself does not appear to be lightning fast; at least a recent Zabbix (1.8.5) on a Debian squeeze \s-1VM\s0 takes a couple seconds to reply to even trivial JSON-RPC queries. This is compounded by the fact that Zabbix::API is being extra paranoid about default values and name/id collisions and fetches data maybe more often than necessary, for instance immediately before and after a \*(C`push()\*(C'.
Several types of objects are not implemented in this distribution; feel free to contribute them or write your own distribution (see Zabbix::API::CRUDE for the gory \s-1API\s0 details).
The \*(C`logout\*(C' business.
The Zabbix \s-1API\s0 documentation, at <http://www.zabbix.com/documentation/start>
LWP::UserAgent
Fabrice Gabolde <[email protected]>
Copyright (C) 2011, 2012, 2013 \s-1SFR\s0
This library is free software; you can redistribute it and/or modify it under the terms of the GPLv3.