PyZabbix

Warnings

• breaking Version 1.0.0 introduced significant changes including API token support and automatic API version detection. Code relying on older manual API version specification or lacking token handling may require updates.
  Fix: Review authentication methods and ensure compatibility with auto-detected API versions. Consider updating authentication to use API tokens if applicable (Zabbix 5.0+).
• gotcha Compatibility with Zabbix server versions is crucial. PyZabbix targets specific Zabbix API versions. Ensure your `pyzabbix` version supports your Zabbix server's API version.
  Fix: Consult the `pyzabbix` GitHub page or changelog for explicit Zabbix server version compatibility. Upgrade `pyzabbix` if your Zabbix server has been updated to a newer major version.
• gotcha Zabbix API errors are encapsulated in `ZabbixAPIException`. Failure to catch this specific exception can lead to unhandled errors, especially when making API calls that might fail (e.g., non-existent IDs, insufficient permissions).
  Fix: Always wrap `pyzabbix` API calls in `try...except ZabbixAPIException` blocks to gracefully handle Zabbix API errors.
• gotcha Authentication management requires careful handling. While `pyzabbix` abstracts `login()`, it's vital to explicitly call `zapi.logout()` after operations or use a context manager (if implemented in future versions) to ensure sessions are properly terminated, especially for long-running applications.
  Fix: Ensure `zapi.logout()` is called in a `finally` block or at the end of your script to prevent stale sessions.

Install

• pip install pyzabbix Install PyZabbix

Imports

• ZabbixAPI

  from pyzabbix import ZabbixAPI

  The PyPI package name is `pyzabbix`, not `zabbix_api`.
• ZabbixAPIException

  from pyzabbix import ZabbixAPIException

  Import for handling API-specific errors returned by the Zabbix server.

Quickstart

This quickstart demonstrates how to connect to the Zabbix API, authenticate using either username/password or an API token (if provided via environment variables), retrieve basic Zabbix server information, and list hosts. It includes error handling for API-specific issues and ensures proper session cleanup with `logout()`.

import os
from pyzabbix import ZabbixAPI, ZabbixAPIException

# Configure Zabbix access via environment variables or replace directly
ZABBIX_URL = os.environ.get('ZABBIX_URL', 'http://localhost/zabbix') # e.g., 'http://your-zabbix-server/zabbix'
ZABBIX_USER = os.environ.get('ZABBIX_USER', 'Admin')
ZABBIX_PASSWORD = os.environ.get('ZABBIX_PASSWORD', 'zabbix') # Default 'zabbix' for Admin user
ZABBIX_TOKEN = os.environ.get('ZABBIX_TOKEN', '') # Optional: for API token authentication

# Initialize zapi outside try-block for finally access
zapi = None

try:
    # Connect to Zabbix API
    zapi = ZabbixAPI(ZABBIX_URL)

    if ZABBIX_TOKEN:
        # Authenticate using API token (requires Zabbix 5.0+ and pyzabbix >= 1.0.0)
        zapi.login(api_token=ZABBIX_TOKEN)
        print("Authenticated using API Token.")
    else:
        # Authenticate using username and password
        zapi.login(ZABBIX_USER, ZABBIX_PASSWORD)
        print(f"Authenticated as user: {ZABBIX_USER}")

    print(f"Connected to Zabbix API version: {zapi.api_version()}")

    # Example: Fetch Zabbix server info
    version_info = zapi.apiinfo.version()
    print(f"Zabbix Server Version: {version_info}")

    # Example: Fetch some hosts
    # 'output' determines which fields are returned, 'selectInterfaces' specifies linked data
    hosts = zapi.host.get(output='extend', selectInterfaces=['interfaceid', 'ip', 'port'])
    print(f"Found {len(hosts)} hosts.")
    if hosts:
        print(f"First host: {hosts[0]['host']} (IP: {hosts[0]['interfaces'][0]['ip']})")

except ZabbixAPIException as e:
    print(f"Error interacting with Zabbix API: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
finally:
    # Ensure proper logout if authenticated
    if zapi and zapi.is_authenticated:
        zapi.logout()
        print("Logged out from Zabbix API.")