---

name: zabbix description: >- Zabbix is an open-source platform for enterprise infrastructure monitoring, configured here with templates, triggers, discovery rules, and the JSON-RPC API. Use when a user needs to set up Zabbix server, configure host monitoring, create custom templates, define trigger expressions, or automate host discovery and registration. license: Apache-2.0 compatibility: "Zabbix 7.0 LTS and 7.4 (server, frontend, Agent 2). Docker Compose for the server; curl and jq for the API calls." metadata: author: terminal-skills version: "1.1.0" category: devops tags: ["zabbix", "enterprise-monitoring", "templates", "triggers", "discovery"] repository: https://github.com/zabbix/zabbix

Zabbix

Overview

Set up Zabbix for enterprise monitoring with host configuration, templates, trigger expressions, low-level discovery, and API automation. Covers server deployment, Agent 2 setup, and host auto-registration. The API calls below were run against Zabbix 7.0.31 and 7.4.15; 6.4 and 7.2 are past end of support.

Instructions

Task A: Deploy Zabbix Server

# docker-compose.yml — Zabbix server with PostgreSQL and web frontend
services:
  zabbix-server:
    image: zabbix/zabbix-server-pgsql:7.0-ubuntu-latest
    environment:
      - DB_SERVER_HOST=postgres
      - POSTGRES_USER=zabbix
      - POSTGRES_PASSWORD=${ZABBIX_DB_PASSWORD:?set ZABBIX_DB_PASSWORD}
      - POSTGRES_DB=zabbix
      - ZBX_CACHESIZE=128M
      - ZBX_HISTORYCACHESIZE=64M
      - ZBX_TRENDCACHESIZE=32M
    ports:
      - "10051:10051"
    depends_on:
      - postgres

  zabbix-web:
    image: zabbix/zabbix-web-nginx-pgsql:7.0-ubuntu-latest
    environment:
      - DB_SERVER_HOST=postgres
      - POSTGRES_USER=zabbix
      - POSTGRES_PASSWORD=${ZABBIX_DB_PASSWORD:?set ZABBIX_DB_PASSWORD}
      - POSTGRES_DB=zabbix
      - ZBX_SERVER_HOST=zabbix-server
      - PHP_TZ=America/New_York
    ports:
      - "8080:8080"
    depends_on:
      - postgres
      - zabbix-server

  postgres:
    image: postgres:16-alpine
    environment:
      - POSTGRES_USER=zabbix
      - POSTGRES_PASSWORD=${ZABBIX_DB_PASSWORD:?set ZABBIX_DB_PASSWORD}
      - POSTGRES_DB=zabbix
    volumes:
      - pg_data:/var/lib/postgresql/data
volumes:
  pg_data:

export ZABBIX_DB_PASSWORD="$(openssl rand -base64 24)"   # keep it in your secrets store
docker compose up -d

The server creates the database schema on first start; the frontend answers on port 8080 after about a minute. The initial login is Admin / zabbix — change it before the port is reachable from anywhere else. Use 7.4-ubuntu-latest for the current standard release; server and frontend tags must match.

Task B: Install and Configure Zabbix Agent 2

# Debian 13 and Ubuntu 26.04 ship Agent 2 7.0 in their own repositories
sudo apt-get update
sudo apt-get install -y zabbix-agent2

On older distributions, or to get the PostgreSQL, MongoDB and MSSQL plugin packages (zabbix-agent2-plugin-postgresql and so on), add the official repository with the commands that https://www.zabbix.com/download generates for your OS. Containers can use the zabbix/zabbix-agent2:7.0-ubuntu-latest image, configured through ZBX_HOSTNAME, ZBX_SERVER_HOST and ZBX_METADATA.

# /etc/zabbix/zabbix_agent2.conf — Agent 2 configuration
Server=192.168.1.5
ServerActive=192.168.1.5
Hostname=web-01.production
HostMetadata=linux:web:production:ubuntu
ListenPort=10050
Timeout=10
Plugins.SystemRun.LogRemoteCommands=1

# Named PostgreSQL session in its own file (root-owned, readable by the zabbix group); the password comes from the environment
sudo install -m 640 -o root -g zabbix /dev/null /etc/zabbix/zabbix_agent2.d/plugins.d/pg-appdb.conf
sudo tee /etc/zabbix/zabbix_agent2.d/plugins.d/pg-appdb.conf >/dev/null <<EOF
Plugins.PostgreSQL.Sessions.appdb.Uri=tcp://localhost:5432
Plugins.PostgreSQL.Sessions.appdb.User=zbx_monitor
Plugins.PostgreSQL.Sessions.appdb.Password=${ZBX_PG_MONITOR_PASSWORD}
EOF
sudo zabbix_agent2 -T                      # validate the configuration
sudo systemctl restart zabbix-agent2
zabbix_agent2 -t 'vfs.fs.size[/,pfree]'    # test one item key locally

Task C: Create Custom Templates via API

export ZABBIX_URL="http://localhost:8080/api_jsonrpc.php"

# Session token from user.login. For automation, export an API token (Users → API tokens) instead.
export ZABBIX_TOKEN=$(curl -s "$ZABBIX_URL" \
  -H "Content-Type: application/json-rpc" \
  -d "$(jq -n --arg u "$ZABBIX_USER" --arg p "$ZABBIX_PASSWORD" \
        '{jsonrpc: "2.0", method: "user.login", params: {username: $u, password: $p}, id: 1}')" \
  | jq -r '.result')

# Helper for every call below: zbx <method> '<params as JSON>'
zbx() {
  curl -s "$ZABBIX_URL" \
    -H "Content-Type: application/json-rpc" \
    -H "Authorization: Bearer $ZABBIX_TOKEN" \
    -d "$(jq -n --arg m "$1" --argjson p "$2" '{jsonrpc: "2.0", method: $m, params: $p, id: 1}')"
}

# Create a custom template in an existing template group
TPL_GROUP_ID=$(zbx templategroup.get '{ "output": ["groupid"], "filter": { "name": ["Templates/Applications"] } }' \
  | jq -r '.result[0].groupid')
TEMPLATE_ID=$(zbx template.create '{
  "host": "Custom Web Application",
  "groups": [{ "groupid": "'"$TPL_GROUP_ID"'" }],
  "description": "Monitors web application health, response times, and error rates",
  "macros": [{ "macro": "{$APP.URL}", "value": "https://shop.corp.internal/healthz" }]
}' | jq -r '.result.templateids[0]')

# Create items (metrics) on the template; {$APP.URL} can be overridden per host
zbx item.create '[
  { "name": "HTTP response time", "key_": "web.page.perf[{$APP.URL}]", "hostid": "'"$TEMPLATE_ID"'",
    "type": 0, "value_type": 0, "delay": "60s", "units": "s" },
  {
    "name": "HTTP status code", "key_": "web.page.get[{$APP.URL}]", "hostid": "'"$TEMPLATE_ID"'",
    "type": 0, "value_type": 3, "delay": "60s",
    "preprocessing": [
      { "type": 5, "params": "HTTP/[0-9.]+ ([0-9]+)\n\\1", "error_handler": 0, "error_handler_params": "" }
    ]
  },
  { "name": "CPU utilization", "key_": "system.cpu.util", "hostid": "'"$TEMPLATE_ID"'",
    "type": 0, "value_type": 0, "delay": "60s", "units": "%" },
  { "name": "Free disk space on /", "key_": "vfs.fs.size[/,pfree]", "hostid": "'"$TEMPLATE_ID"'",
    "type": 0, "value_type": 0, "delay": "5m", "units": "%" }
]'

type 0 is a passive agent check (7 = active, 18 = dependent, 19 = HTTP agent); value_type 0 is float, 3 unsigned integer, 4 text. Preprocessing type is a number (5 = regular expression, 12 = JSONPath) and error_handler is mandatory.

Task D: Define Triggers

# Trigger expressions reference items that already exist on the template
zbx trigger.create '[
  {
    "description": "High CPU usage on {HOST.NAME}",
    "expression": "avg(/Custom Web Application/system.cpu.util,5m)>85",
    "recovery_mode": 1,
    "recovery_expression": "avg(/Custom Web Application/system.cpu.util,5m)<70",
    "priority": 4,
    "manual_close": 1,
    "tags": [{ "tag": "scope", "value": "performance" }, { "tag": "service", "value": "web" }]
  },
  {
    "description": "Disk space critically low on {HOST.NAME}",
    "expression": "last(/Custom Web Application/vfs.fs.size[/,pfree])<10",
    "priority": 5,
    "tags": [{ "tag": "scope", "value": "capacity" }]
  },
  {
    "description": "HTTP response time too high on {HOST.NAME}",
    "expression": "avg(/Custom Web Application/web.page.perf[{$APP.URL}],5m)>3",
    "priority": 3,
    "tags": [{ "tag": "scope", "value": "availability" }]
  }
]'

Task E: Low-Level Discovery

# Discovery rule for running Docker containers (Agent 2 Docker plugin)
RULE_ID=$(zbx discoveryrule.create '{
  "name": "Docker container discovery",
  "key_": "docker.containers.discovery[false]",
  "hostid": "'"$TEMPLATE_ID"'",
  "type": 0, "delay": "5m", "lifetime": "7d"
}' | jq -r '.result.itemids[0]')
# Master item prototype: one JSON document of statistics per discovered container
STATS_ID=$(zbx itemprototype.create '{
  "name": "Container {#NAME}: Get stats",
  "key_": "docker.container_stats[\"{#NAME}\"]",
  "hostid": "'"$TEMPLATE_ID"'",
  "ruleid": "'"$RULE_ID"'",
  "type": 0, "value_type": 4, "delay": "1m", "history": "0"
}' | jq -r '.result.itemids[0]')
# Dependent prototype: extract one number from the master item with JSONPath
zbx itemprototype.create '{
  "name": "Container {#NAME}: CPU percent usage",
  "key_": "docker.container_stats.cpu_pct_usage[\"{#NAME}\"]",
  "hostid": "'"$TEMPLATE_ID"'",
  "ruleid": "'"$RULE_ID"'",
  "type": 18, "master_itemid": "'"$STATS_ID"'",
  "value_type": 0, "units": "%",
  "preprocessing": [
    { "type": 12, "params": "$.cpu_stats.cpu_usage.percent_usage", "error_handler": 0, "error_handler_params": "" }
  ]
}'

Task F: Auto-Registration

# Hosts whose HostMetadata contains the string are created, grouped and linked to the template
WEB_GROUP_ID=$(zbx hostgroup.create '{ "name": "Web servers" }' | jq -r '.result.groupids[0]')
zbx action.create '{
  "name": "Auto-register Linux web servers",
  "eventsource": 2,
  "filter": {
    "evaltype": 0,
    "conditions": [{ "conditiontype": 24, "operator": 2, "value": "linux:web:production" }]
  },
  "operations": [
    { "operationtype": 2 },
    { "operationtype": 4, "opgroup": [{ "groupid": "'"$WEB_GROUP_ID"'" }] },
    { "operationtype": 6, "optemplate": [{ "templateid": "'"$TEMPLATE_ID"'" }] }
  ]
}'

Examples

Example 1: New web servers register themselves

User request: "Every web server we provision should show up in Zabbix with our template, without anyone clicking through the UI."

Run Tasks C, D and F once, then start Agent 2 on the new machine with the Task B configuration (ServerActive pointing at the server, HostMetadata=linux:web:production:ubuntu). Within a minute:

zbx host.get '{ "output": ["host"], "filter": { "host": "web-01.production" },
  "selectHostGroups": ["name"], "selectParentTemplates": ["name"] }' | jq -c '.result'

[{"hostid":"10684","host":"web-01.production","parentTemplates":[{"name":"Custom Web Application"}],"hostgroups":[{"name":"Discovered hosts"},{"name":"Web servers"}]}]

Example 2: An item shows "Not supported"

User request: "The HTTP response time item is red in Zabbix — what is wrong with the key?"

Test the key on the monitored host; the agent prints the value or the reason:

zabbix_agent2 -t 'web.page.perf[https://www.zabbix.com,,,443]'
zabbix_agent2 -t 'web.page.perf[https://www.zabbix.com]'

web.page.perf[https://www.zabbix.com,,,443]   [m|ZBX_NOTSUPPORTED] [Too many parameters.]
web.page.perf[https://www.zabbix.com]         [s|0.275790]

The key takes host,path,port — three parameters at most — and the host may be a full URL. Fix the key on the template with item.update.

Guidelines

• Send the token in the Authorization: Bearer header. The auth property in the request body is deprecated in 7.0 and rejected by 7.4.
• Prefer API tokens with their own user and role over user.login with the Admin account; never leave the Admin / zabbix default login in place.
• An agent must not be newer than the server: a 7.4 agent does not work with a 7.0 server, while older agents keep working after a server upgrade. Proxies must match the server's major version.
• Use Zabbix Agent 2 (Go-based) over legacy Agent for better plugin support and performance
• Link the official templates first ("Linux by Zabbix agent", "Docker by Zabbix agent 2", "PostgreSQL by Zabbix agent 2") and write custom ones only for what they do not cover.
• The Docker plugin needs read access to /var/run/docker.sock — add the zabbix user to the docker group. docker.container_info returns JSON (short or full); per-container numbers come from docker.container_stats through dependent items.
• Use HostMetadata in agent config for automatic registration and template linking; treat it as untrusted input and add encryption (PSK or certificates) when agents register over the internet.
• A trigger with recovery_expression needs recovery_mode: 1; recovery thresholds prevent flapping between OK and PROBLEM states
• Put host-specific values in user macros such as {$APP.URL} so one template serves every host
• Tag triggers and hosts for organized alerting and dashboard filtering