Configuration

zabgrab works without any configuration: it asks for whatever it needs. A config file saves you from typing the same things each time: your servers, your preferred settings, and templates for the fetches you repeat.

Config files

Config files are written in TOML. Open yours in your editor (it’s created if needed) with:

zabgrab config edit

zabgrab checks the file when you close the editor, and offers to reopen it if something’s wrong.

zabgrab reads several files, each overriding the ones before. Most people only need their user config:

1. zabgrab’s built-in defaults.

2. A system config, shared by everyone on the machine: /etc/zabgrab/config.toml (%PROGRAMDATA%\zabgrab\config.toml on Windows).

3. Your user config: ~/.config/zabgrab/config.toml on Linux and macOS (or under $XDG_CONFIG_HOME), %APPDATA%\zabgrab\config.toml on Windows.

4. A project config: the nearest zabgrab.toml in the current directory or its parents (up to your home directory), for settings and templates that belong with a project. zabgrab config edit --target project creates one in the current directory.

5. A file given with --config FILE (or $ZABGRAB_CONFIG).

--isolated ignores the system, user and project files.

To see what’s in effect:

zabgrab config paths            # which files are read, and which exist
zabgrab config show             # the merged configuration
zabgrab config show --sources   # ... with the file each value came from

Settings

[servers.NAME]

A Zabbix server, used by name with --server NAME.

url

The address of the Zabbix web interface.

token_env

An environment variable holding an API token (see Scripts and scheduled jobs). Without it, tokens are kept in your keyring.

auth = "password"

Log in with a username and password instead of an API token.

username

The username to suggest when logging in with a password.

verify_ssl = false

Don’t check the server’s certificate, e.g. for a self-signed one. Only use this on networks you trust.

timeout

Seconds to wait for each request (default 30).

[defaults]

Settings for every fetch, unless a template or the command line says otherwise. Each matches a zabgrab fetch option: server, from, to, resolution, agg, format, output_dir, output_pattern, timezone, jobs and max_items (see Fetching data), plus mat_text_warn_entries: how many text values a .mat file can hold before zabgrab warns that it’ll be big and slow to load (default 200,000; 0 never warns). .h5 files store text far more efficiently.

[templates.NAME]

Named fetches: see Templates.

Example

This example shows every kind of setting. It’s also in the repository as config.example.toml.

# Example zabgrab configuration.
#
# Copy what you need into your user config (`zabgrab config edit` opens it), or into
# a zabgrab.toml in a project directory. Every setting is optional: anything missing
# is asked for when it's needed. `zabgrab config show --sources` shows the merged
# result and where each value came from.

# Zabbix servers, by name. Use a name wherever a server is expected, e.g.
# `zabgrab fetch --server lab`.
[servers.lab]
url = "https://zabbix.lab.example.org"  # the Zabbix web frontend's URL
token_env = "LAB_ZABBIX_TOKEN"          # read the API token from this variable
                                        # (without it, the keyring is used)

[servers.office]
url = "https://zabbix.office.example.org:8443/zabbix"
auth = "password"                       # log in with a username and password
username = "monitoring"                 # the default username, when asked
verify_ssl = false                      # self-signed certificate (insecure)
timeout = 60                            # seconds to wait for each request

# Settings for every fetch, unless the command line or a template sets them.
[defaults]
server = "lab"                          # the server to use without --server
timezone = "Europe/London"              # for times given and shown ("local" by default)
format = "h5"                           # h5, mat, tsv or csv
output_dir = "~/zabbix-data"            # where automatic file names go
output_pattern = "{hosts}_{template}_{from}--{to}"
jobs = 6                                # items downloaded at once
max_items = 50                          # ask before fetching more items than this

# Templates: named, reusable fetches (`zabgrab fetch --template particles`). They
# take the same settings as [defaults], plus the items to fetch.
[templates.particles]
description = "Particle counts in the labs"
items = [
  # Patterns match the whole value, ignoring case, as in the Zabbix API; * matches
  # any text, so "*CPU*" finds names containing "CPU". All given fields must match.
  { host = "lab*", name = "Particles *" },
  { itemid = 12345 },                   # one item, by ID
]
from = "24 hours ago"
to = "now"

[templates.network]
# Ask which server to use, each time.
server = { choices = ["lab", "office"] }
items = [
  { host = "router1", key = "net.if.in[*]" },
  { tag = "component:network" },        # items with this tag (or just "network")
  # Use the first host that has matching items.
  { host = { choices = ["switch-a", "switch-b"], select = "first" }, name = "Uptime" },
]
from = "7 days ago"
to = "now"
resolution = "1h"                       # hourly trends instead of raw values
agg = ["avg", "max"]                    # the trend statistics to save
format = { choices = ["h5", "csv"], select = "all" }  # save both