Zabbix Docker Configuration Reference

This document provides a quick reference for deploying Zabbix agents and proxies using Docker, covering both active and passive modes. It aims to offer easily deployable command-line and Docker Compose snippets for common Zabbix configurations.

1. Zabbix Agent Configurations (Docker)

Zabbix agents collect data from monitored hosts. They can operate in active (agent initiates connection) or passive (server/proxy polls agent) modes.

Active Agent Configuration

In active mode, the agent connects to the Zabbix server/proxy to fetch items for monitoring and sends data. This is often preferred for hosts behind firewalls or when you want the agent to control data submission frequency.

docker run -d \
  --name zabbixagent \
  --restart always \
  -p 10050:10050 \                                           # Expose agent port (optional, mostly for passive checks to agent directly)
  -e ZBX_SERVER_HOST=<ZABBIX_SERVER_OR_PROXY_IP_FOR_PASSIVE> \ # IP of Zabbix server/proxy for passive checks
  -e ZBX_SERVER_ACTIVE=<ZABBIX_SERVER_OR_PROXY_IP_FOR_ACTIVE> \ # IP of Zabbix server/proxy for active checks
  -e ZBX_SERVER_PORT=10052 \                                 # Port to communicate with Zabbix server/proxy (default: 10051)
  -e ZBX_HOSTNAME=$HOSTNAME \                                # Use the system's hostname dynamically for agent registration
  -e ZBX_METADATA=linux \                                    # Host metadata for auto-registration rules
  -v /var/run/docker.sock:/var/run/docker.sock:ro \          # Mount Docker socket for Docker monitoring
  --user 0:0 \                                               # Run as root inside container for full access (e.g., Docker socket)
  zabbix/zabbix-agent2

• ZBX_SERVER_HOST: Specifies the Zabbix server/proxy for passive checks (if any).
• ZBX_SERVER_ACTIVE: Specifies the Zabbix server/proxy for active checks. Multiple IPs can be comma-separated.
• ZBX_SERVER_PORT: The port the Zabbix server/proxy is listening on.

Passive Agent Configuration

In passive mode, the Zabbix server/proxy initiates the connection to the agent to request data. The agent simply listens for these requests.

docker run -d \
  --name zabbixagent \
  --restart always \
  -p 10050:10050 \                                           # Expose agent port for incoming passive checks
  -e ZBX_SERVER_HOST=<ZABBIX_SERVER_OR_PROXY_IP> \           # IP of Zabbix server/proxy that will poll this agent
  -e ZBX_SERVER_PORT=10050 \                                 # Port for communication with Zabbix server/proxy (default: 10051)
  -e ZBX_HOSTNAME=$HOSTNAME \                                # Use the system's hostname dynamically
  -v /var/run/docker.sock:/var/run/docker.sock:ro \          # Mount Docker socket for Docker monitoring
  --user 0:0 \
  zabbix/zabbix-agent2

2. Zabbix Proxy Configurations (Docker Compose)

Zabbix Proxies collect data locally and forward it to the Zabbix Server, reducing load and improving reliability in distributed setups.

Active Proxy Configuration (Proxy pushes data to Server)

In active mode (ZBX_PROXYMODE=0), the proxy initiates the connection to the Zabbix Server and pushes collected data.

version: '3.8'
services:
  zabbix-proxy:
    image: zabbix/zabbix-proxy-mysql:7.0.8-alpine # Use appropriate Zabbix version
    container_name: zabbix-proxy
    environment:
      - DB_SERVER_HOST=<MYSQL_HOST>                # MySQL server hostname or IP for proxy's internal database
      - MYSQL_USER=root                            # MySQL username for the Zabbix proxy's database
      - MYSQL_PASSWORD=<MYSQL_ROOT_PASSWORD>       # WARNING: Hardcoded password, use secrets management in production!
      - ZBX_SERVER_HOST=<ZABBIX_SERVER_IP_OR_HOSTNAME> # IPs or hostnames of the Zabbix servers (comma-separated)
      - ZBX_SERVER_PORT=10051                      # Default Zabbix server port
      - ZBX_PROXYMODE=0                            # 0 for Active (proxy pushes to server), 1 for Passive (server pulls from proxy)
    restart: unless-stopped
    ports:
      - "10052:10051"                              # Expose proxy's data-gathering port if needed (e.g., for agents connecting to proxy)
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

• ZBX_PROXYMODE=0: Configures the proxy to operate in active mode.

Passive Proxy Configuration (Server pulls data from Proxy)

In passive mode (ZBX_PROXYMODE=1), the Zabbix Server initiates connections to the proxy to retrieve collected data.

version: '3.8'
services:
  zabbix-proxy:
    image: zabbix/zabbix-proxy-mysql:7.0.8-alpine
    container_name: zabbix-proxy
    environment:
      - DB_SERVER_HOST=<MYSQL_HOST>
      - MYSQL_USER=root
      - MYSQL_PASSWORD=<MYSQL_ROOT_PASSWORD> # WARNING: Hardcoded password, use secrets management in production!
      - ZBX_SERVER_HOST=<ZABBIX_SERVER_IP_OR_HOSTNAME>
      - ZBX_SERVER_PORT=10051
      - ZBX_PROXYMODE=1                            # 1 for Passive (server pulls from proxy)
    restart: unless-stopped
    ports:
      - "10052:10051"
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

• ZBX_PROXYMODE=1: Configures the proxy to operate in passive mode.

3. Zabbix API URL for Grafana

If you are integrating Zabbix with Grafana, you will typically configure the Zabbix data source in Grafana to point to the Zabbix API endpoint.

URL: http://<ZabbixFrontendHostname>/api_jsonrpc.php

This is the standard JSON-RPC API endpoint for Zabbix, used by various integrations.