ZC-INTRO(7) - Miscellaneous Information Manual

NAME

zc-intro - introduction to the zc command line tools

DESCRIPTION

Working with the zabbix APIs without resorting to the usage of powerful tools like python or perl can be difficult. However, day to day tasks, like closing a series of problems, or fetching some history values, should not be difficult because of that.

zc(1) represents a series of commands, written in C, that make heavy use of the canonical UNIX shell facilities (pipes etc..) for integrating the zabbix APIs in a shell environment. The main design goal of the zc(1) commands, is to be usable in conjunction of powerful tools like awk(1) and with more canonical tools such as grep(1) and cut(1).

It must be noted that zc(1) is NOT a replacement for the flexibility of using the zabbix APIs with a powerful programming language like perl(1), but it is meant to make the most common tasks easily scriptable.

LICENSE

The project is released under the ISC license

DESIGN

zc(1) is composed by a main command (the entry point), with a series of sub commands, meant to perform only one task. All the sub commands can be called independently, thus allowing, in a future, scenarios where more high level commands can combine, themselves, different zc(1) sub commands if required.

All the sub commands are implemented as different binaries, and they share a common set of code that handle the JSON rpc part with a zabbix web frontend.

Allowing sessions to be started and terminated, for example on a cron job, is done by saving the authentication token and the related http URL in the user's home directory, for being used by subsequent requests.

Another main design decision, was to decide if a command could perform different configuration change operations, like acknowledging and closing a problem with the same binary. From a semantic point of view, it was decided that, instead of cluttering sub commands with different flags, a main modification operation must be implemented by another command, even if they call the same API. combining different actions, is done by properly allowing the sub commands to work in pipelines. For example, the following one-liner:

$ zc problem get -b 2019-02-18T00:00:00 | cut -f 1 |
    zc problem ack -m "acknowledged" | zc problem close

will:

Fetch all the problems opened after February 18, 2019.
Acknowledge all the problems with a message "acknowledged".
Close all the problems.

DEPENDENCIES

zc(1) depends on:

libcurl
libnghttp2
libssl
libcrypto
zlib
libpthread

For the portable version, please check the zc-portable repository.

INSTALLATION

If it doesn't exist, create the zc directory for the command binaries under /usr/local/libexec.

# mkdir -p /usr/local/libexec/zc
# chown root:wheel /usr/local/libexec/zc
# chmod 0755 /usr/local/libexec/zc

After extracting the tar.gz file, from inside the project directory:

$ make obj
$ make
# make install

Once the binaries and man pages are installed, for having the man pages properly indexed, run:

# makewhatis

BASIC USAGE

The first thing to do, is authenticating zc(1) with a zabbix server. We store the authentication informations in the "prod" authentication context. If no context is specified, "default" is used:

$ zc -c prod auth -u user -p password http[s]://server/api_jsonrpc.php

Where the path is the full URL to the zabbix APIs php file (as described in the zabbix documentation).

If the authentication is successful, it will be possible to perform operations like:

$ zc -c prod host get
10084	enabled	unavailable	Zabbix server

for retrieving the list of all monitored hosts or:

$ export ZC_CTX=prod
$ zc item add passive -d 1m -h 10326 -i 59 \
    -n "Number of running processes" -s 7d -r 365d \
    -t num 'proc.nump[]'
31922
$ zc item get -h 'Zabbix server' 'Number of running processes'
31922   10326   1m      proc.nump[]     Number of running processes

For creating a new zabbix agent passive check. In the example, the item is a check named "Number of running processes" with a history and trends retention period of 7 and 365 days, part of the host with id 10326 of type unsigned number.

We exported the "prod" context first, thus setting it as the default one in the current shell, without the need to specify it on the command line every time.

After the monitoring start to collect data, it's possible to fetch data for a particular item:

$ zc history float -s 2019-04-01T00:00:00 31922
31922	1554132473	0.5370	152883791
31922	1554132533	0.5280	753532397
31922	1554132593	0.5370	342977311
31922	1554132653	0.5281	943250782
31922	1554132713	0.5370	533437503
31922	1554132773	0.5370	123361077
31922	1554132833	0.5281	723530353
31922	1554132893	0.5538	313831844
31922	1554132953	0.5116	913494776
31922	1554133013	0.5370	504180284

Once done, closing the session in the exported "prod" context is easy:

$ zc close

Or if we didn't exported it:

$ zc -c prod close

Every sub command, have it's own man page, so it's easy to learn how to use all the implemented commands.

AUTHORS

Andrea Biscuola <a@abiscuola.com>

OpenBSD 6.9 - April 14, 2020

zc

Documentation