Zabbix Agent Update Manager

Read this in other languages:

Zabbix Agent Update Manager is an enterprise-grade frontend module for Zabbix 6.4 and 7.0+ LTS. It centralizes agent lifecycle management, cross-references installed agent versions across all monitored Linux, Windows, and FreeBSD hosts against official Zabbix release branches, identifies hardware and virtualization architectures, and provides automated, copy-paste ready upgrade commands tailored to each host's operating system.

Developed by George Filho.

---

🎯 Main Features

• 🌐 Multi-Source Version Resolution Engine:

  • Primary Provider: Fetches official stable releases from https://cdn.zabbix.com with mandatory strict SSL validation.
  • Secondary Fallback: GitHub Releases / Tags API fallback for high availability.
  • Air-Gapped / Offline Support: Embedded static version database for fully isolated enterprise environments.
  • Automatically isolates major branches (6.0.x, 6.4.x, 7.0.x, 7.2.x, 7.4.x).

• 📊 High-Level KPI Summary Dashboard:

  • Real-time KPI summary cards displaying Total Monitored Hosts, Physical Hosts (Bare-Metal), Virtual Machines (VMs), Up to Date, Outdated (Update Needed), Offline (Unreachable), and Unknown Version.

• 🖥️ Modular Hardware & Hypervisor Detection (HardwareDetectionService):

  • Identifies Physical Bare-Metal Servers (Dell PowerEdge, HPE ProLiant, Lenovo ThinkServer/ThinkSystem, Supermicro, Cisco UCS) vs. Virtual Machines (VMware ESXi, Proxmox, KVM/QEMU, Hyper-V, VirtualBox, Xen, AWS EC2, GCP, Azure, Nutanix).
  • Passive DMI/WMI telemetry without requiring custom remote scripts.

• 🐧 Decoupled 5-Layer OS Engine (OsDetectionService):

  • Natively identifies Linux distributions (Fedora, Debian, Ubuntu, RHEL, Rocky, AlmaLinux, CentOS, openSUSE, Alpine, FreeBSD) and Windows Editions (Windows Server 2025, 2022, 2019, 2016, Windows 11/10).

• 📑 Native Pagination for Massive Scale (CPagerHelper):

  • Seamlessly handles large enterprise infrastructures (+10,000 hosts) with fluent pagination and configurable page limits.

• 🔍 Advanced Multi-Dimensional Filtering:

  • Filter by Host Name/IP, Status, OS Family, Hardware Type, Host Group, and Zabbix Proxy.

• 📋 Host Details Modal:

  • Click any host name to open an extended information panel showing IP, OS Family, Raw OS Info, Interface Type, Agent Version, and a timestamped Version History log (last 5 upgrades).

• 📥 Direct CSV Export:

  • Instant one-click CSV export with UTF-8 BOM (Excel compatible) of all filtered hosts including Hardware Type (Container LXC, VM, Cloud, Physical), OS, version gaps, and availability status.

• 🤖 Automated Batch & Ansible Playbooks:

  • Interactive modal with per-host instructions and dynamic mass update command generators (SSH Batch / Ansible Playbooks).

• 🔒 Hardened Security & CSP Compliance:

  • Strict SSL verification, exclusive cache locking (LOCK_EX & chmod 0600), zero inline scripts, and no hardcoded credentials.

---

📋 Prerequisites

Before installing this module, ensure that:

1. You are running Zabbix Frontend 6.4 LTS, 7.0 LTS, or higher.
2. The web server user (e.g., www-data, apache, or nginx) has read access to the module directory.
3. The PHP curl extension or allow_url_fopen is enabled to allow fetching official Zabbix release version information from cdn.zabbix.com (proxies supported via standard environment variables https_proxy / http_proxy).

---

🚀 Installation

Installing modules in the Zabbix frontend is straightforward and plug-and-play.

1. Download or clone this repository:

Download the module files to your Zabbix server.

2. Copy to the Zabbix modules directory:

Move the module folder into the modules directory of your Zabbix web interface.

Important

The module folder must be placed inside modules/ keeping the name Module Agent Update (with spaces), exactly as provided in this repository.

The default module path on most distributions is:

# Ubuntu / Debian
cp -r "Module Agent Update" /usr/share/zabbix/ui/modules/

# RHEL / Rocky Linux / AlmaLinux / CentOS
cp -r "Module Agent Update" /usr/share/zabbix/modules/

3. Set proper file permissions:

Ensure the web server user has read access to all module files:

# Debian / Ubuntu (Nginx / Apache)
chown -R www-data:www-data "/usr/share/zabbix/ui/modules/Module Agent Update"
chmod -R 755 "/usr/share/zabbix/ui/modules/Module Agent Update"

# Allow the web server to write runtime cache files
chmod -R 777 "/usr/share/zabbix/ui/modules/Module Agent Update/data"

# RHEL / Rocky / Alma / CentOS (Apache / Nginx)
chown -R apache:apache "/usr/share/zabbix/modules/Module Agent Update"
chmod -R 755 "/usr/share/zabbix/modules/Module Agent Update"
chmod -R 777 "/usr/share/zabbix/modules/Module Agent Update/data"

4. Enable the Module in Zabbix Frontend:

1. Log into your Zabbix Web Interface as a Super Admin.
2. Navigate to Administration → General → Modules (or Administration → Modules in Zabbix 7.0).
3. Click the "Scan directory" button in the top right corner.
4. Locate "Zabbix Agent Update Manager" in the list.
5. In the Status column, click Disabled to change it to Enabled.

---

💻 How to Use

Once enabled, a new dedicated menu item will be accessible in your Zabbix main navigation:

1. Navigate to SuporTI → Agent Updates in the left sidebar menu.
2. Review Global KPI Cards: View an instant summary of outdated servers, physical machines, and virtual machines.
3. Filter Hosts: Use the top filter form to filter by:
   • Host / IP: Search by hostname, DNS, or interface IP address.
   • Status: Filter by Outdated only, Up to date only, Offline, or Unknown version.
   • OS Family: Filter by Linux, Windows, FreeBSD, or Unknown.
   • Hardware Type: Filter by Physical, Virtual (VM), Cloud, or Unknown.
   • Host Group and Proxy for additional segmentation.
4. Inspect Version Gaps: Review the side-by-side Current Version and Target Version columns.
5. Get Update Instructions: For any outdated host, click the Instructions button to open the interactive upgrade modal with exact commands for your operating system and package manager.
6. Host Details: Click any host name in the table to view the extended Host Details modal, including OS details, interface type, agent version, and the last 5 detected version changes.
7. Export CSV: Click Export CSV in the header to download a full spreadsheet of all filtered hosts.
8. Bulk Actions: Select multiple hosts via the checkboxes, then copy their IPs or generate a batch update script in one click.

---

🔍 Real Operating System Detection (Server-Side Script)

To display the exact, official distribution name and version (e.g., Ubuntu 22.04.4 LTS, Debian GNU/Linux 12 (bookworm), Microsoft Windows Server 2022 Datacenter) in the Operating System column, the module includes automated scanning scripts executed directly on the Zabbix Server.

Key Highlights:

• Zero Configuration on Monitored Agents: Does not require remote commands (AllowKey=system.run[*]) or creating custom UserParameter keys on target machines.
• Native Zabbix Agent Keys:
  • Linux: Reads /etc/os-release via vfs.file.contents[/etc/os-release] and extracts PRETTY_NAME=.
  • Windows: Queries WMI via wmi.get[root\cimv2,select Caption from Win32_OperatingSystem] or queries the official OS caption.
• Zero-Token Database Auto-Discovery: Connects directly via PDO to the local Zabbix database (MySQL or PostgreSQL) by parsing /etc/zabbix/web/zabbix.conf.php, without needing API tokens or web sessions.

Important

SNMP Hosts: OS and Hardware detection are not supported for hosts monitored exclusively via SNMP (without Zabbix Agent installed). Both the Operating System and Hardware columns will display a grey Not Collected badge for these hosts, ensuring no false positives are shown.

---

Execution and Automation Procedures

1. Manual Scan for All Hosts (--all):

On the Zabbix server terminal, navigate to the module directory and execute:

cd "/usr/share/zabbix/ui/modules/Module Agent Update"
php scripts/detect_real_os.php --all

# Or via Bash:
bash scripts/detect_real_os.sh --all

2. Manual Scan for an Individual Host:

php scripts/detect_real_os.php --ip=192.168.1.100 --hostid=10084

# Or via Bash:
bash scripts/detect_real_os.sh 192.168.1.100 10084

---

⚙️ Integration with Zabbix UI (Alerts → Scripts)

You can register the script directly in the Zabbix Web UI to scan any host on-demand with 1 click:

1. Navigate to Alerts → Scripts (or Administration → Scripts).
2. Click Create script:
   • Name: Detect Real OS
   • Scope: Check Action operation and/or Manual host action (enables 1-click execution from the Hosts page).
   • Type: Script
   • Execute on: Zabbix proxy or server
   • Commands:

     /usr/share/zabbix/ui/modules/Module\ Agent\ Update/scripts/detect_real_os.php "{HOST.CONN}" "{HOST.ID}"

3. Click Add / Update.
4. How to test: Go to Monitoring → Hosts, click on any monitored host name, and select Detect Real OS. A pop-up modal will instantly display the real-time execution output.

Script configuration in Zabbix Alerts → Scripts for on-demand OS detection from the Hosts page.

---

⏰ Weekly Automation (7-Day Revalidation Cycle)

To ensure operating system data remains continuously validated without manual overhead, use one of the following methods:

Method A: Via Linux Crontab (Recommended 🌟)

On the Zabbix server, run crontab -e as root and schedule the task to run weekly (e.g., every Sunday at 03:00 AM):

# Runs weekly every 7 days and outputs to a dedicated log file
0 3 * * 0 /usr/bin/php "/usr/share/zabbix/ui/modules/Module Agent Update/scripts/detect_real_os.php" --all > /var/log/zabbix/detect_real_os.log 2>&1

To inspect the output of the latest execution:

cat /var/log/zabbix/detect_real_os.log

Method B: Via Native Zabbix Item (External Check)

1. Create a symlink in the Zabbix Server external scripts directory:

   ln -s "/usr/share/zabbix/ui/modules/Module Agent Update/scripts/detect_real_os.sh" /usr/lib/zabbix/externalscripts/detect_real_os_all.sh
   chmod +x /usr/lib/zabbix/externalscripts/detect_real_os_all.sh

2. Create an Item on the Zabbix server host:
   • Type: External check
   • Key: detect_real_os_all.sh["--all"]
   • Update interval: 0
   • Custom intervals: Scheduling wd7h3 (Every Sunday at 03:00 AM)

---

🛡️ False Positive Prevention (Not Collected)

If a host is offline, unreachable, the agent times out, or is monitored only via SNMP:

• The script explicitly records the status as Not Collected in cache (for offline/timeout scenarios).
• SNMP-only hosts are automatically assigned Not Collected without attempting any collection.
• The user interface renders the neutral Not Collected badge with an explanatory tooltip on mouse hover.
• This strictly avoids displaying outdated or irrelevant historical guesses, maintaining 100% inventory fidelity.

---

🖥️ Automated Hardware & Virtualization Detection (VM vs Container vs Cloud vs Physical Server)

To ensure the Hardware column displays with pinpoint accuracy whether a host is a Virtual Machine (VM), a Container (LXC / Docker), a Cloud Instance (AWS / GCP / Azure), or a Physical Server (Bare-Metal) along with its specific hardware/hypervisor model, the module includes multi-tiered scanner logic with anti-false-positive isolation:

How It Works:

• Tier 1: Container Detection (LXC / Docker / Podman):
  • LXC containers (common on Proxmox VE) inherit DMI vendor/model tables and kernel from the host node (e.g. Dell PowerEdge).
  • The scanner checks systemd-detect-virt, Chassis: container, Icon: computer-container, and native markers /run/systemd/container, /proc/1/cgroup, and /proc/1/environ.
  • Result: Accurately labels containers as Container · LXC, completely eliminating false positives where containers were misidentified as the physical host server!
• Tier 2: Cloud Instance Detection (AWS / GCP / Azure / OCI / DigitalOcean):
  • Cloud instances (such as AWS Nitro c5/m5/t3) report chassis as server.
  • The scanner identifies cloud providers via DMI and virtualization hypervisors, categorizing as Cloud · AWS EC2 (t3.medium), Cloud · GCP Instance, or Cloud · Azure VM.
• Tier 3: Hypervisors & Virtual Machines (KVM / QEMU / VMware / Hyper-V / VirtualBox / Xen):
  • Inspects the CPU hypervisor flag in /proc/cpuinfo (strictly exclusive to virtualized CPUs), Virtualization: tags, and virtual DMI (QEMU Standard PC, VMware Virtual Platform, Virtual Machine).
  • Categorizes as VM · KVM / QEMU, VM · VMware, or VM · Hyper-V.
• Tier 4: Genuine Physical Bare-Metal Servers:
  • Only hosts that do not possess container, cloud, or CPU hypervisor markers and belong to verified hardware manufacturers (Dell, HPE, Lenovo, Supermicro, Cisco, etc.) are categorized as Physical · Dell PowerEdge R740 or Physical · HPE ProLiant.
• Windows (Win32_ComputerSystem):
  • Native Zabbix Agent WMI queries and PowerShell Get-CimInstance Win32_ComputerSystem map physical vs. virtual platforms with full parity.
• Dedicated Local Cache: Results are stored in data/real_hw_cache.json and rendered on a single line with distinct theme-adaptive color accents.

Important

SNMP Hosts: Hardware detection is not supported for hosts monitored via SNMP only. These hosts display Not Collected in the Hardware column.

---

Executing Hardware Detection Scripts

1. Hardware Scan Across All Hosts (--all):

cd "/usr/share/zabbix/ui/modules/Module Agent Update"
php scripts/detect_hardware.php --all

# Or via Bash:
bash scripts/detect_hardware.sh --all

2. Hardware Scan for a Specific Host:

php scripts/detect_hardware.php --ip=192.168.1.100 --hostid=10084

# Or via Bash:
bash scripts/detect_hardware.sh 192.168.1.100 10084

3. Unified Full Scan (OS + Hardware in One Shot!):

To scan and refresh both Operating System and Hardware across all hosts in a single command:

bash scripts/detect_all.sh --all

---

⚙️ Integration with Zabbix UI (Alerts → Scripts)

Register the hardware scanner in the Zabbix Web UI for 1-click on-demand execution:

1. Navigate to Alerts → Scripts → Create script:
   • Name: Detect Real Hardware
   • Scope: Check Action operation and Manual host action.
   • Type: Script
   • Execute on: Zabbix proxy or server
   • Commands:

     /usr/bin/php /usr/share/zabbix/ui/modules/Module\ Agent\ Update/scripts/detect_hardware.php "{HOST.CONN}" "{HOST.ID}"

2. Click Add / Update.
3. In Monitoring → Hosts, left-click any host name and select Detect Real Hardware to view real-time diagnostics!

Script configuration in Zabbix Alerts → Scripts for on-demand Hardware detection from the Hosts page.

---

⏰ Weekly Unified Automation (Every 7 Days)

On the Zabbix server, run crontab -e as root and schedule the full weekly scan:

# Runs full weekly revalidation (OS + Hardware) every Sunday at 03:00 AM
0 3 * * 0 "/usr/share/zabbix/ui/modules/Module Agent Update/scripts/detect_all.sh" --all > /var/log/zabbix/detect_all.log 2>&1

---

📂 Directory Structure

The structure follows the official Zabbix 6.4+ / 7.0+ MVC Module Architecture:

Module Agent Update/
├── .gitignore                     # Excludes runtime data and sensitive keys from version control
├── manifest.json                  # Module metadata, actions, and assets manifest
├── Module.php                     # Core module class and main navigation menu registration
├── README.md                      # English documentation
├── README_pt.md                   # Portuguese documentation
├── actions/
│   └── AgentUpdateList.php        # Primary Controller
├── includes/
│   ├── AvailabilityResolver.php   # Availability and agent interface resolution
│   ├── CsvExportService.php       # Structured CSV export (UTF-8 with BOM)
│   ├── HardwareDetectionService.php # Hardware type resolution (Physical vs VM) with cache
│   ├── HostFilterService.php      # Dynamic multi-criteria host filtering
│   ├── OsDetectionService.php     # Multi-layer OS detection and cache loader
│   ├── VersionHistoryService.php  # Temporal version history and stale tracker
│   └── ZabbixVersionFetcher.php   # Official CDN scraper and HMAC cache
├── scripts/
│   ├── agent_update_alert.php     # Optional: Push agent status to Zabbix via API (Zabbix 7.0+)
│   ├── detect_all.sh              # Unified scanner script for both OS and Hardware
│   ├── detect_hardware.php        # CLI PHP script to scan and cache Hardware (VM vs Physical)
│   ├── detect_hardware.sh         # Bash wrapper script for Hardware scan
│   ├── detect_real_os.php         # CLI PHP script to scan and cache real OS for all hosts
│   └── detect_real_os.sh          # Bash wrapper script for OS scan
├── data/                          # Runtime cache (excluded from version control via .gitignore)
│   ├── .hmac_key                  # Auto-generated HMAC signing key (chmod 0600)
│   ├── real_hw_cache.json         # Real Hardware cache (VM vs Physical)
│   ├── real_os_cache.json         # Real OS cache per host
│   └── zbx_agent_version_cache.json # Official Zabbix releases cache
├── views/
│   └── agent.update.list.php      # Main view (KPIs, Filters, Hosts table, and Modal)
└── assets/
    ├── css/
    │   └── module.css             # Theme-adaptive styling (Dark, Light, HC-Dark)
    ├── js/
    │   └── module.js              # CSP-compliant interactions, column sorting, and bulk selection
    └── images/
        ├── image-01.png              # Main Dashboard & Full Hosts Table
        ├── image-02.png              # Batch Automation Modal (Ansible Script)
        ├── image-03.png              # Per-Host Update Instructions Modal
        ├── image-04.png              # Header Action Buttons
        ├── image-05.png              # KPI Cards & Filter Bar
        ├── image-06.png              # Host Details Modal (Extended Info & Version History)
        ├── image-07.png              # Outdated vs Up to Date Row Examples
        ├── image-detect_real_os.png  # Zabbix Alerts → Scripts: Detect Real OS configuration
        └── image-detect_hardware.png # Zabbix Alerts → Scripts: Detect Real Hardware configuration

---

🖼️ Screenshots

1. Main Dashboard & Inventory View

Full host table view with Availability, OS, Hardware, Current/Target versions, Status badges, and Actions.

2. KPI Cards & Multi-Criteria Filter Bar

Real-time KPI summary cards (Total, Up to Date, Outdated, Offline, Unknown, Physical, VM) and the advanced multi-criteria filter bar.

3. Interactive Upgrade Instructions Modal

Tailored upgrade instructions per OS with Agent 2 (Go), Agent 1 (C), Windows MSI download shortcuts, and one-click copy feedback.

4. Batch Automation & Ansible Playbooks

Mass update command generator with SSH batch scripts and Ansible playbooks for all outdated hosts.

5. Host Details Modal (Version History)

Extended host information panel with IP, OS Family, Interface Type, Agent Version, and timestamped Version History.

6. Outdated vs Up to Date Row Examples

Highlighted Outdated badge with "patches behind" counter, compared to a fully up-to-date row. Container · LXC Hardware badge visible.

7. Zabbix Script: Detect Real OS Configuration

How to register the Detect Real OS script in Zabbix Alerts → Scripts for on-demand 1-click execution from the Hosts page.

8. Zabbix Script: Detect Real Hardware Configuration

How to register the Detect Real Hardware script in Zabbix Alerts → Scripts for on-demand 1-click execution from the Hosts page.

---

🛠️ Technical Details

Important

Collection Compatibility & Support (Zabbix Agent Required): Automated collection and detection of Operating System and Hardware are supported exclusively on servers with Zabbix Agent (or Agent 2) installed and active. For servers or network appliances monitored exclusively via SNMP (or without Zabbix Agent installed), collection is not performed, and both columns will cleanly display Not Collected (subtle grey badge), ensuring only 100% verified agent data is presented and eliminating false positives.

Intelligent Multi-Layer OS Resolution Waterfall

The module resolves operating system information using a passive cascading architecture (requires Zabbix Agent):

0. Real OS Cache (data/real_os_cache.json generated by server-side scan script via zabbix_get)
1. vfs.file.contents[/etc/os-release] (systemd standard PRETTY_NAME=)
2. Windows WMI (Win32_OperatingSystem)
3. system.sw.os[full] / system.sw.os (Zabbix template software OS items)
4. vfs.file.contents[/etc/redhat-release] / /etc/issue (Legacy RHEL/CentOS)
5. Host Inventory (os_full, os_short, os populated by agent)
6. system.uname (Kernel release parsing: .fcXX ➔ Fedora, .elX ➔ Enterprise Linux, Ubuntu, Debian, Windows)

Hardware & Virtualization Architecture Resolution

Identifies hardware architectures through (requires Zabbix Agent):

• Real Hardware Cache (data/real_hw_cache.json generated by server-side scan script via zabbix_get)
• Native OS commands: hostnamectl (Linux) and Get-CimInstance Win32_ComputerSystem (Windows)
• Container markers: /run/systemd/container, /proc/1/cgroup (LXC / Docker / Podman)
• DMI / WMI tables: /sys/class/dmi/id/product_name, sys_vendor, chassis_type, Win32_ComputerSystem, Win32_BIOS
• Contextual fallback through Template names, Host Groups, and Tags.

Security Architecture

• Input Validation: All HTTP inputs strictly validated via Zabbix's validateInput() with an explicit allowlist.
• Permission Enforcement: Module requires USER_TYPE_ZABBIX_ADMIN or higher.
• SSL Enforcement: CURLOPT_SSL_VERIFYPEER = true and CURLOPT_SSL_VERIFYHOST = 2 — no exceptions.
• Cache File Security: Written with LOCK_EX (atomic) and chmod 0600 (owner-read-only).
• CSP Compliance: Zero inline scripts. All JavaScript uses DOM API methods (createElement, textContent, setAttribute).
• No Hardcoded Credentials: API token scripts use environment variables (ZABBIX_API_TOKEN).

---

📄 License & Credits

Copyright © 2006-2026 by George Filho.

All rights reserved.