dbaio / pybix

Python based Zabbix API utility with helper functions

pybix

NOTE: This module is still in development and may not be fully stable. Use at own risk.

Description

Python based Zabbix API utility containing helper functions and CLI capabilities.

Takes inspiration from existing Python-Zabbix API modules like lukecyca/pyzabbix and adubkov/py-zabbix.

While this module can be used in a similar way, the aim is to add a few out of the box helper functions and CLI handling for a more "batteries included" module. For example GraphImage as described in usage which enables saving Zabbix graphs which is not possible via the API at this time.

Install

Pip

pip install pybix

Docker

TODO - not yet available.

Requirements

• Python 3.6 or greater
• Zabbix 2.0 or greater
  • Only tested on >4.0

Usage

Zabbix API

Refer to Zabbix Offical API object references for objects that can be queried and their parameters.

API structure all uses format like ZAPI.<object>.<action>(<parameters>) e.g. ZAPI.host.get(output='extend').

Import as Python module

Directly

from pybix import ZabbixAPI
ZAPI = ZabbixAPI(url="http://localhost/zabbix")
ZAPI.login(user="Admin", password="zabbix")

# Print all monitored hosts
for host in ZAPI.host.get(output="extend",monitored_hosts=1):
    print(host['host'])

ZAPI.logout() # Explicitly logout to clear Zabbix session

With context manager to handle logout

Note: Login still must be done manually (as in the future we may allow passing existing session, hence might not need to login everytime).

from pybix import ZabbixAPI

with ZabbixAPI() as ZAPI: # using defaults for server
    ZAPI.login() # using defaults for user, password

    # Print all monitored hosts
    for host in ZAPI.host.get(output="extend",monitored_hosts=1):
        print(host['host'])

Zabbix API CLI

Zabbix API CLI Usage

Usage:
    pybix.py <method> [--zabbix-server=ZABBIX_SERVER] [--zabbix-user=ZABBIX_USER]
            [--zabbix-password=ZABBIX_PASSWORD] [--ssl-verify] [(-v | --verbose)] [<args> ...]
    pybix.py (-h | --help)
    pybix.py --version

Arguments:
  method        either Zabbix API reference as '<object>.<action>' or GraphImage API as 'graphimage.<search_type>' (e.g. 'host.get' or 'graphimage.graph_id')
  args          what arguments to pass to API call

Options:
  -h, --help
  --version
  -v, --verbose                      Whether to use verbose logging [default: False]
  --output-path=PATH                 Where to save graphs to default: cwd
  --zabbix-server=ZABBIX_SERVER      [default: https://localhost/zabbix]
  --zabbix-user=ZABBIX_USER          [default: Admin]
  --zabbix-password=ZABBIX_PASSWORD  [default: zabbix]
  --ssl-verify                       Whether to use SSL verification for API [default: True]

Zabbix API CLI Example

python -m pybix host.get filter="{host:server1}" # Get host server1
python -m pybix host.get filter="{host:[server1,server2]}" # Get host server1 and server2
python -m pybix user.get # Get all Users

Graph Image Export

Zabbix does not let you export graphs via API (only the configuration for them). Instead of using ZabbixAPI class, use included GraphImage.

GraphImage Python Example

from pybix import GraphImageAPI
graph = GraphImageAPI(url="http://localhost/zabbix",
                      user="Admin",
                      password="zabbix")
graph.get_by_graph_id("4038") # will save to png file in current working directory
graph.get_by_graphname("CPU") # will save any "CPU" graph png images to file in current working directory

GraphImage CLI

GraphImage CLI Usage

Refer to ZabbixAPI usage.

search_types include graph_id, graph_name, item_names, item_keys, item_ids

GraphImage CLI Examples

python -m pybix graphimage.graph_name graph_name=CPU host_names=server1
python -m pybix graphimage.graph_name graph_name=CPU host_names=[server1,server2]
python -m pybix graphimage.item_names item_names=CPU host_names=server1
python -m pybix graphimage.item_keys item_keys=availability.agent.available host_names=server1

# Not as useful, but is what above methods call after calculating id
python -m pybix graphimage.graph_id graph_id=4038 host_names=server1
python -m pybix graphimage.item_ids item_ids=138780,138781 host_names=server1

Known Issues

SSL Verification

• If server using a self signed cert or serving on HTTPS, will need to use ssl_verify overide

User configuration

• Zabbix user used during API calls must have viewing rights to queried Zabbix object
  • i.e. appropriate hostgroup read rights to user/usergroup OR super admin
  • If it does not, it will simply return empty results without warning

Graph Items Usage

• User used to login must have frontend access (i.e. in Zabbix user group, set frontend access to true)
• No error messages or warnings if graph is invalid (i.e. wrong values used to call it)

Contributing

Feel free to raise any feature requests/problems/improvements as issue or pull request via GitHub.