Zabbix-CLI v3 has been completely rewritten from the ground up. The old version can be found here.
Zabbix-cli is a command line interface for performing common administrative tasks tasks in Zabbix monitoring system via the Zabbix API.
The zabbix-cli code is written in Python and distributed under the GNU General Public License v3. It has been developed and tested by University Center for Information Technology at the University of Oslo, Norway.
The project home page is on GitHub. Please report any issues or improvements there.
The manual is available online at https://unioslo.github.io/zabbix-cli/.
Install with pip:
pip install git+https://github.com/unioslo/zabbix-cli.git@master
# Initialize the config file with your Zabbix URL
zabbix-cli init --zabbix-url https://your-zabbix-url.com/
# Start the REPL
zabbix-cli
Zabbix-cli supports two output formats: table and JSON. The default format is table, but it can be changed with the --format
parameter or by setting the app.output_format
parameter in the config file.
# Show hosts in table format (default)
zabbix-cli show_hosts
# Show hosts in JSON format
zabbix-cli --format json show_hosts
# Setting format in REPL
> --format json show_hosts
Zabbix-cli is a command line interface for Zabbix. It can be used in three ways:
- Interactive mode: Start the REPL by running
zabbix-cli
. This will start a shell where you can run multiple commands in a persistent session. - Single command: Run a single command by running
zabbix-cli COMMAND
. This will run the command and print the output. - Batch mode: Run multiple commands from a file by running
zabbix-cli -f FILE
. The file should contain one command per line.
Command reference can be found in the online user guide or by running zabbix-cli --help
.
Zabbix-cli needs a config file. This can be created with the zabbix-cli init
command.
zabbix-cli init --zabbix-url https://zabbix.example.com/
Zabbix-cli will look for config files in the following order:
- The path specified with the
--config
parameter ./zabbix-cli.toml
- XDG config directory (usually
~/.config/zabbix-cli/zabbix-cli.toml
), or equivalent Platformdirs directory on Windows and macOS - XDG site config directory (usually
/etc/xdg/zabbix-cli/zabbix-cli.toml
), or equivalent Platformdirs directory on Windows and macOS
To show the directories used by the application run:
zabbix-cli show_dirs
To open the default config directory with the default window manager run:
zabbix-cli open config
Or print the path to the default config directory:
zabbix-cli open config --path
Zabbix-cli provides commands for showing the current and default configuration:
zabbix-cli show_config
zabbix-cli sample_config
If you run into problems it is useful to enable debug logging in the config file:
[logging]
enabled = true
log_level = "DEBUG"
Find the log file with:
zabbix-cli open logs
Zabbix-cli provides several ways to authenticate. They are tried in the following order if multiple are set:
- API token in config file
- API token in file (if
use_auth_token_file=true
) - Username and password in config file
- Username and password in auth file
- Username and password in environment variables
- Username and password from prompt
Username and password-based authentication is the default and easiest way to authenticate, but also the least secure.
The password can be set directly in the config file:
[api]
zabbix_url = "https://zabbix.example.com/"
username = "Admin"
password = "zabbix"
By omitting the password
parameter in the config file, you will be prompted for a password when running zabbix-cli:
[api]
zabbix_url = "https://zabbix.example.com/"
username = "Admin"
An auth file named .zabbix-cli_auth
can be created in the user's home directory. The content of this file should be in the USERNAME::PASSWORD
format.
echo "Admin::zabbix" > ~/.zabbix-cli_auth
The file is automatically loaded if it exists and the password
parameter is not set in the config file. The location of the file can be changed in the config file:
[app]
auth_file = "/path/to/auth/file"
The username and password can be set as environment variables:
export ZABBIX_USERNAME="Admin"
export ZABBIX_PASSWORD="zabbix"
These are automatically loaded if the password
parameter is not set in the config file.
Once you have authenticated with a username and password, zabbix-cli will store a session token if you configure use_auth_token_file=true
in the config. This way you don't need to provide your credentials each time you run zabbix-cli. The token file should also be secured properly.
[app]
use_auth_token_file = true
The location of the auth token file can be changed in the config file:
[app]
auth_token_file = "/path/to/auth/token/file"
Zabbix-cli also supports authentication with an API token specified directly in the config file:
[api]
auth_token = "API_TOKEN"
[app]
use_auth_token_file = false
Zabbix-cli currently uses Hatch for project management and packaging. To start off, clone the repository:
git clone https://github.com/unioslo/zabbix-cli.git
Then make a virtual environment using Hatch:
hatch shell
This will create a new virtual environment, install the required dependencies and enter the environment.
Run unit tests (without coverage):
hatch run test
Generate coverage report:
hatch run cov
To serve the documentation locally:
hatch run docs:serve
This will start a local web server on http://localhost:8001
that is automatically refreshed when you make changes to the documentation. However, some hooks are only run on startup, such as the creation of pages for each command. Changes to command examples or docstrings will require a restart.