Scripts and scheduled jobs

zabgrab asks questions when something’s missing, which is convenient at a terminal but no use in a script or a scheduled job. This page covers running it unattended.

When zabgrab asks, and when it doesn’t

zabgrab only asks questions when it’s running in a terminal. It never asks when:

  • its input or error output isn’t a terminal (in a pipe, a cron job, a CI job, …);

  • --no-input is given;

  • $ZABGRAB_NO_INPUT is set (to anything but 0);

  • $CI is set (as CI services do).

Then, instead of asking:

  • a question that needs an answer (which server, what time range, which format) stops zabgrab with an error that says exactly how to give the answer, such as the option to pass or the config setting to add;

  • a yes/no question takes its default answer, with a warning (e.g. a fetch matching more than max_items items fetches them all);

  • an existing output file is kept, and the data saved next to it under a new name (pass --overwrite to replace it);

  • without --output, the data is fetched but not saved (with a warning).

So the reliable way to script zabgrab is to give everything on the command line or in a template, and to try the command once by hand with --no-input:

zabgrab --no-input fetch -t particles --from "1 hour ago" --to now -o data/

After any fetch where you answered questions, zabgrab prints the equivalent command (Next time: ...), which is a good starting point for a script.

Logging in without a keyring

Scheduled jobs often run where there’s no keyring, or a locked one. Give them the API token in an environment variable instead, named in the server’s config:

[servers.lab]
url = "https://zabbix.example.org"
token_env = "LAB_ZABBIX_TOKEN"

zabgrab uses the variable when it’s set, and the keyring otherwise. zabgrab token list shows where each server’s token comes from, and zabgrab token list --check checks they work.

Warning

Treat API tokens like passwords: keep them out of scripts, version control and command lines. Load them from a file only you can read, or from your scheduler’s secret store. Give tokens an expiry date in Zabbix, and use an account that can only read what the job needs.

A scheduled update

For example, to add the latest data to a file every morning with cron:

# crontab -e
# m  h  dom mon dow  command
15   6  *   *   *    . $HOME/.zabbix-token && $HOME/.local/bin/zabgrab update $HOME/data/particles.h5 >> $HOME/data/update.log 2>&1

where ~/.zabbix-token (readable only by you: chmod 600) contains export LAB_ZABBIX_TOKEN=.... Use the full path to zabgrab, since cron’s PATH is minimal; which zabgrab shows it.

Exit status

zabgrab’s exit status tells a script how it went:

Status

Meaning

0

Success.

1

An error: nothing was done (or saved).

2

A mistake on the command line, such as an unknown option.

3

Some items couldn’t be fetched, but the others were saved.

130

Cancelled (Ctrl+C, or cancelled at a question).

Output

zabgrab writes data (tables, TOML) to standard output, and everything else (progress, messages, warnings, errors) to standard error. So you can pipe or redirect tables without the messages getting mixed in:

zabgrab items --host lab1 > items.txt

Progress bars only show in a terminal. -q hides messages, -qq hides warnings too (errors always show), and -v shows more detail. Colour is off when output isn’t a terminal or $NO_COLOR is set; --color and --no-color force it. Add --debug to see full tracebacks for errors.

Global options such as these can go before or after the command: zabgrab -q update file.h5 and zabgrab update file.h5 -q are the same.