zc-intro - introduction to the zc command line tools
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.
The project is released under the ISC license
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
- Fetch all the problems opened after February 18, 2019.
- Acknowledge all the problems with a message "acknowledged".
- Close all the problems.
zc(1) depends on:
- A C compiler (gcc and clang are supported)
If it doesn't exist, create the zc directory for the command binaries under /usr/local/libexec. and the man page directories under /usr/local/man/man1 and /usr/local/man/man7
# mkdir -p /usr/local/libexec/zc # mkdir -p /usr/local/man/man1 # mkdir -p /usr/local/man/man7 # chown root:wheel /usr/local/libexec/zc # chmod 0755 /usr/local/libexec/zc
After extracting the tar.gz file, from inside the project directory:
$ ./mkgen.sh $ make # make install
Currently, zc-portable works on:
- RHEL/CentOS 7
- Alpine linux
On Debian and derivatives, /bin/sh is symlinked to dash. This causes an error with a condition in the ./mkgen.sh script.
To avoid the problem, call the script with bash instead:
$ bash ./mkgen.sh
Alpine linux uses the musl libc by default. This means the sys/cdefs.h header doesn't exists in a standard installation. To compile zc-portable(1) you need to install the libbsd and libbsd-dev packages:
# apk add libbsd libbsd-dev
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.
Andrea Biscuola <firstname.lastname@example.org>