From 02a16f007986daa023441dbe90f112ca9fbee6f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=81=AB=E6=98=9F=E5=B0=8F=E5=88=98?= Date: Sun, 6 Sep 2026 10:21:52 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3=E4=BB=8B?= =?UTF-8?q?=E7=BB=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 34 +++++-- README_en.md | 67 +++++++++--- zabbix_ipam/README.md | 70 ++++++++++++- zabbix_ipam/README_en.md | 214 ++++++++++++++++++++++++++++++++++++++- 4 files changed, 359 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index e22fe05..1fe87bb 100644 --- a/README.md +++ b/README.md @@ -193,25 +193,46 @@ **兼容性**：Zabbix 6.0.x, 7.0.x, 7.4.x, 8.0.x +### 9. Zabbix IPAM + +**简介**：用于集中管理 IPv4 地址段并执行异步 ICMP 存活扫描的 Zabbix 前端模块，可按主机接口 IP 自动关联 Zabbix 主机。 + +**功能特性**： + +- 支持 CIDR 和 IPv4 起止地址格式，单个地址段最多 65,536 个地址 +- 基于 `fping` 的 ICMP 存活扫描，不探测 TCP 端口 +- 大网段自动分片，PHP CLI 后台执行，支持 `pcntl` 多进程 +- 支持手动扫描与 crontab 定时扫描，并实时显示任务进度 +- IP 使用矩阵、地址明细、主机关联、筛选与分页 +- 支持中英文界面国际化 + +![1](zabbix_ipam/images/1.png) +![2](zabbix_ipam/images/2.png) +![3](zabbix_ipam/images/3.png) + +**文档链接**：[zabbix_ipam/README.md](./zabbix_ipam/README.md)（[English](./zabbix_ipam/README_en.md)） + +**兼容性**：Zabbix 6.0.x, 7.0.x, 7.4.x, 8.0.x + ## 安装说明 ### 方式一：下载 Releases 压缩包（适合生产部署，按需选择） Releases 页面提供两种压缩包，无需安装 git： -- **整体打包压缩包**：`zabbix_modules-<版本号>.tar.gz`（包含所有模块，版本号格式：`模块数量.大版本.小版本`，如 `8.2.0`） +- **整体打包压缩包**：`zabbix_modules-<版本号>.tar.gz`（包含所有模块，版本号格式：`模块数量.大版本.小版本`，如 `13.2.0`） - **单模块压缩包**：`zabbix_<模块名>-<版本号>.tar.gz`（按需下载单个模块） #### 选项 A：下载所有模块整体压缩包 -1. 前往 [Releases 页面](https://github.com/X-Mars/zabbix_modules/releases)，下载 `zabbix_modules-<版本号>.tar.gz` 文件（如 `zabbix_modules-8.2.0.tar.gz`） +1. 前往 [Releases 页面](https://github.com/X-Mars/zabbix_modules/releases)，下载 `zabbix_modules-<版本号>.tar.gz` 文件（如 `zabbix_modules-13.2.0.tar.gz`） 2. 上传到 Zabbix 服务器并解压到模块目录： ```bash # Zabbix 6.0 / 7.0 tar -xzf zabbix_modules-<版本号>.tar.gz -C /usr/share/zabbix/modules/ -# Zabbix 7.2+ / 7.4 / 8.0 +# Zabbix 6.4 / 7.2 / 7.4 / 8.0 tar -xzf zabbix_modules-<版本号>.tar.gz -C /usr/share/zabbix/ui/modules/ ``` @@ -223,7 +244,7 @@ for mod in /usr/share/zabbix/modules/zabbix_*/; do done ``` -如果使用 Zabbix 7.0+ 或 8.0+，则无需修改，保持默认值即可。 +如果使用 Zabbix 6.4、7.0+ 或 8.0+，则无需修改，保持默认值即可。 #### 选项 B：下载单个模块 @@ -244,7 +265,7 @@ tar -xzf zabbix_<模块名>-<版本号>.tar.gz -C /usr/share/zabbix/ui/modules/ sed -i 's/"manifest_version": 2.0/"manifest_version": 1.0/' /usr/share/zabbix/modules/zabbix_<模块名>/manifest.json ``` -如果使用 Zabbix 7.0+ 或 8.0+，则无需修改，保持默认值即可。 +如果使用 Zabbix 6.4、7.0+ 或 8.0+，则无需修改，保持默认值即可。 ### 方式二：git clone 直接部署（适合开发/跟踪更新） @@ -276,7 +297,7 @@ sed -i 's/"manifest_version": 2.0/"manifest_version": 1.0/' /usr/share/zabbix/mo sed -i 's/"manifest_version": 2.0/"manifest_version": 1.0/' /usr/share/zabbix/modules/zabbix_reports/manifest.json ``` -如果使用 Zabbix 7.0+ 或 8.0+，则无需修改，保持默认值即可。 +如果使用 Zabbix 6.4、7.0+ 或 8.0+，则无需修改，保持默认值即可。 ### 启用模块 @@ -302,6 +323,7 @@ sed -i 's/"manifest_version": 2.0/"manifest_version": 1.0/' /usr/share/zabbix/mo - **资产记录 → JumpServer** (JumpServer 同步) - **Users → IM同步助手** (IM 同步 / 同步设置) - **数据采集 → 主机批量导入** (基于源主机批量克隆主机) +- **Inventory → IPAM** (IP 管理 / IP 详情 / 任务管理) ### 单独安装模块 diff --git a/README_en.md b/README_en.md index 645798c..a6882e8 100644 --- a/README_en.md +++ b/README_en.md @@ -25,7 +25,7 @@ This repository contains a collection of independent Zabbix frontend modules tha ![1](zabbix_reports/images/1.png) ![2](zabbix_reports/images/2.png) -- **Docs**: [zabbix_reports/README.md](./zabbix_reports/README.md) +- **Docs**: [zabbix_reports/README_en.md](./zabbix_reports/README_en.md) ### 2. Zabbix CMDB @@ -36,7 +36,7 @@ This repository contains a collection of independent Zabbix frontend modules tha ![2](zabbix_cmdb/images/2.png) ![3](zabbix_cmdb/images/3.jpg) -- **Docs**: [zabbix_cmdb/README.md](./zabbix_cmdb/README.md) +- **Docs**: [zabbix_cmdb/README_en.md](./zabbix_cmdb/README_en.md) ### 3. Zabbix Graph Trees @@ -46,7 +46,7 @@ This repository contains a collection of independent Zabbix frontend modules tha ![1](zabbix_graphtrees/images/1.png) ![2](zabbix_graphtrees/images/2.png) -- **Docs**: [zabbix_graphtrees/README.md](./zabbix_graphtrees/README.md) +- **Docs**: [zabbix_graphtrees/README_en.md](./zabbix_graphtrees/README_en.md) ### 4. Zabbix Rack @@ -57,7 +57,7 @@ This repository contains a collection of independent Zabbix frontend modules tha ![2](zabbix_rack/images/2.png) ![3](zabbix_rack/images/3.png) -- **Docs**: [zabbix_rack/README.md](./zabbix_rack/README.md) +- **Docs**: [zabbix_rack/README_en.md](./zabbix_rack/README_en.md) ### 5. Zabbix SNMP @@ -68,7 +68,7 @@ This repository contains a collection of independent Zabbix frontend modules tha ![2](zabbix_snmp/images/2.png) ![3](zabbix_snmp/images/3.png) -- **Docs**: [zabbix_snmp/README.md](./zabbix_snmp/README.md) +- **Docs**: [zabbix_snmp/README_en.md](./zabbix_snmp/README_en.md) ### 6. Zabbix JumpServer @@ -77,18 +77,18 @@ This repository contains a collection of independent Zabbix frontend modules tha ![1](zabbix_jumpserver/images/1.png) -- **Docs**: [zabbix_jumpserver/README.md](./zabbix_jumpserver/README.md) +- **Docs**: [zabbix_jumpserver/README_en.md](./zabbix_jumpserver/README_en.md) ### 7. IM Sync Assistant - **Purpose**: Sync **WeCom**, **Feishu**, and **DingTalk** org structures into Zabbix **user groups**, and match or create Zabbix users with group membership. - **Features**: multi-platform support; web UI for sync credentials (**Users → Sync Settings**, one active setting at a time); department sync with optional full-path group names; user sync with match/auto-create (12-char password shown once in results); DingTalk users without mobile get pinyin usernames from display name; preview before sync; bilingual UI. -![1](images/1.png) -![2](images/2.png) -![3](images/3.png) +![1](zabbix_im/images/1.png) +![2](zabbix_im/images/2.png) +![3](zabbix_im/images/3.png) -- **Docs**: [zabbix_im/README_en.md](./zabbix_im/README_en.md)（[中文](./zabbix_im/README.md)） +- **Docs**: [zabbix_im/README_en.md](./zabbix_im/README_en.md) ([中文](./zabbix_im/README.md)) ### 8. Zabbix Clonehosts @@ -100,7 +100,43 @@ This repository contains a collection of independent Zabbix frontend modules tha ![3](zabbix_clonehosts/images/image-2.png) ![4](zabbix_clonehosts/images/image-3.png) -- **Docs**: [zabbix_clonehosts/README_en.md](./zabbix_clonehosts/README_en.md)（[中文](./zabbix_clonehosts/README.md)） +- **Docs**: [zabbix_clonehosts/README_en.md](./zabbix_clonehosts/README_en.md) ([中文](./zabbix_clonehosts/README.md)) + +### 9. Zabbix IPAM + +- **Purpose**: Centrally manage IPv4 ranges, run asynchronous ICMP availability scans, and associate addresses with Zabbix hosts by interface IP. +- **Features**: CIDR and start-end ranges up to 65,536 addresses; `fping`-based ICMP-only scans; automatic sharding and optional `pcntl` workers; manual and cron scans; live task progress; address matrix, filtering, pagination, and host links; bilingual UI. + +![1](zabbix_ipam/images/1.png) +![2](zabbix_ipam/images/2.png) +![3](zabbix_ipam/images/3.png) + +- **Docs**: [zabbix_ipam/README_en.md](./zabbix_ipam/README_en.md) ([中文](./zabbix_ipam/README.md)) + +### 10. Zabbix LLDP Topology + +- **Purpose**: Visualize LLDP neighbor relationships from Zabbix LLDP discovery items. +- **Features**: filter hosts/groups by **Lldp Discovery** template; group/host dropdowns with all-groups/all-hosts defaults; on-demand query loading `lldp.remote.info[*]` values; SVG circles and lines (local left, remote right); hover tooltips with ports and update time; bilingual UI. + +- **Docs**: [zabbix_lldp/README_en.md](./zabbix_lldp/README_en.md) ([中文](./zabbix_lldp/README.md)) + +### 11. Zabbix Clouds + +- **Purpose**: Synchronize Alibaba Cloud ECS, Huawei Cloud ECS, and Tencent Cloud CVM instances to Zabbix. +- **Features**: preview-before-sync workflow; idempotent matching through the `cloud_instance_id` tag; automatic `Clouds/{Provider}/{Region}` host groups; soft marking for cloud-deleted managed hosts; cloud account configuration. +- **Docs**: [zabbix_clouds/README_en.md](./zabbix_clouds/README_en.md) ([中文](./zabbix_clouds/README.md)) + +### 12. Zabbix Rightsizing + +- **Purpose**: Generate CPU and memory sizing recommendations from Zabbix data over a selected period. +- **Features**: trends-first analysis with history fallback; CPU and memory recommendations; result export; configurable analysis parameters; bilingual UI. +- **Docs**: [zabbix_rightsizing/README_en.md](./zabbix_rightsizing/README_en.md) ([中文](./zabbix_rightsizing/README.md)) + +### 13. Zabbix Switch Backup + +- **Purpose**: List, preview, and download switch configuration backup files from Zabbix. +- **Features**: file metadata and newest-first ordering; text preview and downloads; traversal and symlink protection; role-based access controls; bilingual UI. +- **Docs**: [zabbix_switch_backup/README_en.md](./zabbix_switch_backup/README_en.md) ([中文](./zabbix_switch_backup/README.md)) ## Installation @@ -108,12 +144,12 @@ This repository contains a collection of independent Zabbix frontend modules tha The Releases page offers two types of packages — no git required: -- **All-in-one package**: `zabbix_modules-.tar.gz` (includes all modules; version format: `module_count.major.minor`, e.g., `8.2.0`) +- **All-in-one package**: `zabbix_modules-.tar.gz` (includes all modules; version format: `module_count.major.minor`, e.g., `13.2.0`) - **Single-module package**: `zabbix_-.tar.gz` (download only the modules you need) #### Option A: Download the all-in-one package -1. Go to the [Releases page](https://github.com/X-Mars/zabbix_modules/releases) and download the `zabbix_modules-.tar.gz` file (e.g., `zabbix_modules-8.2.0.tar.gz`). +1. Go to the [Releases page](https://github.com/X-Mars/zabbix_modules/releases) and download the `zabbix_modules-.tar.gz` file (e.g., `zabbix_modules-13.2.0.tar.gz`). 2. Upload to the Zabbix server and extract to the modules directory: ```bash @@ -201,6 +237,11 @@ After enabling and refreshing the UI, the modules appear under the following men - **Inventory → JumpServer** - **Users → IM Sync Assistant** (IM Sync / Sync Settings) - **Data collection → Host Batch Import** (batch clone hosts from a source host) +- **Monitoring → LLDP Topology** (LLDP neighbor topology) +- **Inventory → IPAM** (IP Management / IP Details / Task Management) +- **Inventory → Cloud Sync** (Cloud Hosts / Cloud Settings) +- **Inventory → Rightsizing** (resource sizing recommendations) +- **Inventory → Switch Backup** (switch configuration backups) Each module contains its own README with specific installation and usage details. diff --git a/zabbix_ipam/README.md b/zabbix_ipam/README.md index 6889ce3..7a3c85a 100644 --- a/zabbix_ipam/README.md +++ b/zabbix_ipam/README.md @@ -15,7 +15,7 @@ ## 描述 -这是一个 Zabbix 前端 IP 地址管理模块，用于集中维护 IPv4 地址段、执行异步 ICMP 存活扫描，并根据 Zabbix 主机接口 IP 自动建立主机关联。模块在 Zabbix Web 的资产记录菜单下新增“IP 管理”菜单，包含“IP 管理”“IP 详情”和“任务管理”三个页面。 +这是一个 Zabbix 前端 IP 地址管理模块，用于集中维护 IPv4 地址段、执行异步 ICMP 存活扫描，并根据 Zabbix 主机接口 IP 自动建立主机关联。模块在 Zabbix Web 的 **Inventory（资产记录）→ IPAM** 下提供“IP 管理”“IP 详情”和“任务管理”三个页面。 扫描仅使用 ICMP，不会连接目标 TCP 端口。大网段会自动分片，并由后台 PHP CLI 任务执行，避免阻塞 Zabbix Web 请求。 @@ -41,6 +41,25 @@ - **响应式设计**：取消固定最大宽度，适配普通、宽屏和窄屏浏览器 - **安全限制**：仅 Zabbix 管理员可访问，输入均经过 IPv4 和数值校验 +## 工作方式 + +```text +IP 管理页面 / crontab + ↓ +创建地址段扫描任务 + ↓ +PHP CLI 后台进程 + ↓ +按 64 个地址分片 → fping ICMP 探测 + ↓ +JSON 结果与任务进度 → IP 矩阵 / IP 详情 / 任务管理 +``` + +- 在 Web 页面点击“开始扫描”时，模块通过 PHP `exec()` 和 `nohup` 启动独立的 PHP CLI 进程。 +- 定时扫描由 `cli/scan_cron.php` 直接执行；每次 cron 运行都会为所有已启用且没有待处理/运行中任务的地址段创建扫描任务。 +- CLI 环境支持 `pcntl_fork()` 时最多并行运行 4 个工作进程；不支持时自动串行执行。 +- 扫描状态和结果以 JSON 文件保存，写入时使用文件锁及临时文件原子替换，便于 Web 与 cron 同时访问。 + ## 安装步骤 ### 安装模块 @@ -64,7 +83,7 @@ sed -i 's/"manifest_version": 2.0/"manifest_version": 1.0/' zabbix_ipam/manifest ### 配置目录权限 -运行 Web 服务和 cron 的用户必须能够读写 `data/`、`data/scan_tasks/` 和 `data/results/`。 +运行 Web 服务和 cron 的用户都必须能够读写 `data/`、`data/scan_tasks/` 和 `data/results/`。建议使用同一用户；如使用不同用户，请通过共同用户组授予读写权限。以下命令中的路径应替换为模块的实际安装路径。 ```bash # Debian / Ubuntu 示例 @@ -86,7 +105,21 @@ apt install fping php-cli php-pcntl dnf install fping php-cli php-process ``` -`php-pcntl` 或 `php-process` 用于多进程扫描；未安装 `pcntl` 时会自动降级为后台串行扫描。PHP CLI 和 `fping` 是后台扫描的必要依赖。 +`php-pcntl` 或 `php-process` 用于多进程扫描；未安装 `pcntl` 时会自动降级为后台串行扫描。PHP CLI 和 `fping` 是扫描的必要依赖。 + +安装后建议使用 Web 服务用户检查运行环境： + +```bash +# Debian / Ubuntu +sudo -u www-data /usr/bin/php -r 'echo PHP_SAPI, PHP_EOL;' +sudo -u www-data /usr/bin/fping -c 1 -t 350 127.0.0.1 + +# RHEL / Rocky Linux +sudo -u apache /usr/bin/php -r 'echo PHP_SAPI, PHP_EOL;' +sudo -u apache /usr/sbin/fping -c 1 -t 350 127.0.0.1 +``` + +如需从 Web 页面手动启动扫描，请确认 PHP 未禁用 `exec`，并允许 Web 服务用户运行 PHP CLI。若安全策略禁止 `exec`，仍可仅使用下文的 cron 定时扫描入口。 ### 启用模块 @@ -97,13 +130,30 @@ dnf install fping php-cli php-process ## 定时扫描 -`cli/scan_cron.php` 是唯一定时扫描入口，crontab 的执行频率就是扫描间隔。以下示例每 5 分钟扫描一次所有已启用的 IP 段；已有待处理或运行中的任务不会被重复创建。 +`cli/scan_cron.php` 是唯一定时扫描入口，crontab 的执行频率就是扫描间隔。以下示例每 5 分钟扫描一次所有已启用的 IP 段；已有待处理或运行中的任务不会被重复创建。请勿使用 `root` 运行扫描。 + +写入 `/etc/cron.d/zabbix-ipam` 时需要包含运行用户： ```cron */5 * * * * apache /usr/bin/php /usr/share/zabbix/modules/zabbix_ipam/cli/scan_cron.php >> /var/log/zabbix/ipam-cron.log 2>&1 ``` -Debian / Ubuntu 通常将运行用户改为 `www-data`。任务状态文件和工作锁会避免同一 IP 段被重复提交。 +Debian / Ubuntu 通常将运行用户改为 `www-data`。如果使用 `crontab -u apache -e` 或 `crontab -u www-data -e`，则不要在表达式中再次写用户名： + +```cron +*/5 * * * * /usr/bin/php /usr/share/zabbix/modules/zabbix_ipam/cli/scan_cron.php >> /var/log/zabbix/ipam-cron.log 2>&1 +``` + +Zabbix 7.2+ / 7.4 / 8.0 的脚本路径通常是 `/usr/share/zabbix/ui/modules/zabbix_ipam/cli/scan_cron.php`。请确保日志目录也允许对应用户写入；任务状态文件和工作锁会避免同一 IP 段被重复提交。 + +### 手动验证 cron 入口 + +```bash +# 按实际环境选择 apache 或 www-data，并替换模块路径 +sudo -u apache /usr/bin/php /usr/share/zabbix/modules/zabbix_ipam/cli/scan_cron.php +``` + +命令无输出且任务页出现新任务通常表示执行成功；错误信息会输出到标准错误流。 ## 页面说明 @@ -119,10 +169,20 @@ Debian / Ubuntu 通常将运行用户改为 `www-data`。任务状态文件和 - **地址限制**：仅支持 IPv4，单个 IP 段最多 65,536 个地址。 - **系统权限**：Zabbix Web 用户和 cron 用户必须能够写入模块 `data/` 目录。 - **ICMP 权限**：请确保服务器防火墙允许 ICMP，并允许 `fping` 正常运行。 +- **命令执行**：Web 手动扫描依赖 PHP `exec()`；使用 cron 时不依赖 Web 请求启动后台进程。 - **性能考虑**：大网段会分片处理；并行工作进程默认最多为 4 个。 - **主机匹配**：关联结果来自当前用户有权访问的 Zabbix 主机接口数据。 - **数据存储**：当前使用 JSON 文件，生产环境请定期备份 `data/` 目录。 +## 故障排查 + +- **点击开始扫描后立即失败**：检查 PHP CLI 是否存在、PHP `exec()` 是否被禁用，以及 `data/scan_tasks/` 是否可写。 +- **所有地址均显示不可达**：以 Web/cron 用户直接运行 `fping`，确认安装路径、执行权限、防火墙和 ICMP 策略。模块会依次查找 `/usr/sbin/fping`、`/usr/bin/fping` 和 `/sbin/fping`。 +- **任务一直处于待处理状态**：检查 `data/scan_tasks/<任务 ID>.log`、PHP CLI 路径和 SELinux/AppArmor 限制。 +- **cron 没有创建任务**：确认地址段已启用，并检查是否已经存在同一地址段的 `pending` 或 `running` 任务。 +- **页面无法保存地址段**：检查 `data/` 所有权与权限；模块需要创建锁文件和临时 JSON 文件。 +- **没有关联到主机**：确认 Zabbix 主机接口使用的是相同 IPv4 地址，并确认当前登录用户有权查看该主机。 + ## 开发 插件基于 Zabbix 模块框架开发。主要文件结构： diff --git a/zabbix_ipam/README_en.md b/zabbix_ipam/README_en.md index eb78deb..ed6edcc 100644 --- a/zabbix_ipam/README_en.md +++ b/zabbix_ipam/README_en.md @@ -1,3 +1,213 @@ -# Zabbix IPAM +# Zabbix IPAM Module -See [README.md](README.md) for installation, cron configuration, asynchronous shard scanning, dependencies and operational safeguards. The module supports Zabbix 6.0, 7.x and 8.0 and appears under Inventory → IPAM. +[中文](README.md) + +## ✨ Version Compatibility + +This module is compatible with Zabbix 6.0, 7.0+, and 8.0+. + +- ✅ Zabbix 6.0.x +- ✅ Zabbix 7.0.x +- ✅ Zabbix 7.4.x +- ✅ Zabbix 8.0.x + +**Compatibility note**: The module includes Zabbix version detection and a custom `LanguageManager`. It automatically handles namespace and menu API differences and follows the user's Zabbix language setting, so no manual language selection is required. + +## Description + +This Zabbix frontend IP address management module centrally manages IPv4 ranges, performs asynchronous ICMP availability scans, and automatically associates addresses with Zabbix hosts by matching host interface IPs. It provides three pages under **Inventory → IPAM** in Zabbix Web: **IP Management**, **IP Details**, and **Task Management**. + +Scanning uses ICMP only and does not connect to target TCP ports. Large ranges are automatically divided into shards and processed by background PHP CLI tasks, preventing long-running Zabbix Web requests. + +![1](images/1.png) +![2](images/2.png) +![3](images/3.png) + +## Features + +- **IP range management**: Add, edit, and delete ranges in CIDR or IPv4 start-end format +- **Automatic filtering**: Press Enter in a search field to filter; select fields submit automatically +- **ICMP availability scanning**: Use `fping` to check whether addresses are reachable without probing TCP ports +- **Asynchronous tasks**: Create tasks from the Web UI and run them in the background with PHP CLI +- **Sharding and multiprocessing**: Use shards of 64 addresses by default and support parallel scans through `pcntl_fork` +- **Live progress**: Display scanned and reachable address counts, completed shard counts, and task status +- **Scheduled scanning**: Define the scan interval with crontab; each invocation scans every enabled IP range +- **IP usage matrix**: Display reachability using green and gray address cells +- **IP details list**: Show the IP address, range name, range, reachability status, and host association +- **Automatic host association**: Match Zabbix hosts by their interface IPv4 addresses +- **Latest data links**: Open a host's latest data page from its name in the list or from an associated reachable address in the matrix +- **Pagination**: Paginate every list and allow users to select the number of rows per page +- **Internationalization**: Follow the Zabbix user language automatically, with Simplified Chinese and English support +- **Responsive design**: Adapt to standard, wide, and narrow browser viewports without a fixed maximum width +- **Access and input controls**: Restrict access to Zabbix administrators and validate IPv4 and numeric input + +## How It Works + +```text +IP Management page / crontab + ↓ +Create an IP range scan task + ↓ +Background PHP CLI process + ↓ +Split into 64-address shards → fping ICMP probes + ↓ +JSON results and task progress → IP matrix / IP Details / Task Management +``` + +- When a user clicks **Start scan** in the Web UI, the module starts a separate PHP CLI process through PHP `exec()` and `nohup`. +- Scheduled scans run directly through `cli/scan_cron.php`. Each cron invocation creates tasks for all enabled ranges that do not already have a pending or running task. +- When `pcntl_fork()` is available in the CLI environment, the scanner runs up to four worker processes in parallel. Otherwise, it automatically runs serially. +- Scan status and results are stored in JSON files. Writes use file locks and atomic replacement through temporary files so that Web and cron processes can access the data concurrently. + +## Installation + +### Install the Module + +```bash +# Common module path for Zabbix 6.0 / 7.0 +cp -a zabbix_ipam /usr/share/zabbix/modules/ + +# Common module path for Zabbix 7.2+ / 7.4 / 8.0 +cp -a zabbix_ipam /usr/share/zabbix/ui/modules/ +``` + +Use the `$ZBX_MODULES_DIR` value configured for your Zabbix frontend if its module directory differs from these examples. + +### ⚠️ Change manifest.json When Required + +```bash +# ⚠️ Run only if Zabbix 6.0 cannot recognize manifest_version 2.0 +sed -i 's/"manifest_version": 2.0/"manifest_version": 1.0/' zabbix_ipam/manifest.json +``` + +### Configure Directory Permissions + +Both the Web service user and the cron user must be able to read and write `data/`, `data/scan_tasks/`, and `data/results/`. Using the same account is recommended. If different accounts are used, grant access through a shared group. Replace the paths below with the module's actual installation path. + +```bash +# Debian / Ubuntu example +chown -R www-data:www-data zabbix_ipam/data +chmod -R 770 zabbix_ipam/data + +# RHEL / Rocky Linux example +chown -R apache:apache zabbix_ipam/data +chmod -R 770 zabbix_ipam/data +``` + +### Install Scan Dependencies + +```bash +# Debian / Ubuntu +apt install fping php-cli php-pcntl + +# RHEL / Rocky Linux +dnf install fping php-cli php-process +``` + +`php-pcntl` or `php-process` enables multiprocessing. Without `pcntl`, the module automatically falls back to serial background scanning. PHP CLI and `fping` are required for scanning. + +After installation, verify the runtime as the Web service user: + +```bash +# Debian / Ubuntu +sudo -u www-data /usr/bin/php -r 'echo PHP_SAPI, PHP_EOL;' +sudo -u www-data /usr/bin/fping -c 1 -t 350 127.0.0.1 + +# RHEL / Rocky Linux +sudo -u apache /usr/bin/php -r 'echo PHP_SAPI, PHP_EOL;' +sudo -u apache /usr/sbin/fping -c 1 -t 350 127.0.0.1 +``` + +To start scans manually from the Web UI, make sure PHP has not disabled `exec` and that the Web service user is allowed to run PHP CLI. If your security policy prohibits `exec`, you can still use only the scheduled cron entry point described below. + +### Enable the Module + +1. Go to **Administration → General → Modules**. +2. Click **Scan directory** to discover newly installed modules. +3. Find the **IPAM** module and enable it. +4. Refresh the page. The **Inventory → IPAM** menu will contain **IP Management**, **IP Details**, and **Task Management**. + +## Scheduled Scanning + +`cli/scan_cron.php` is the only scheduled scan entry point. The crontab frequency defines the scan interval. The following examples scan all enabled IP ranges every five minutes. A duplicate task is not created when the same range already has a pending or running task. Do not run scans as `root`. + +When creating `/etc/cron.d/zabbix-ipam`, include the account that runs the command: + +```cron +*/5 * * * * apache /usr/bin/php /usr/share/zabbix/modules/zabbix_ipam/cli/scan_cron.php >> /var/log/zabbix/ipam-cron.log 2>&1 +``` + +On Debian and Ubuntu, replace `apache` with `www-data` in most installations. When using `crontab -u apache -e` or `crontab -u www-data -e`, do not include the username again in the cron expression: + +```cron +*/5 * * * * /usr/bin/php /usr/share/zabbix/modules/zabbix_ipam/cli/scan_cron.php >> /var/log/zabbix/ipam-cron.log 2>&1 +``` + +For Zabbix 7.2+, 7.4, and 8.0, the script path is commonly `/usr/share/zabbix/ui/modules/zabbix_ipam/cli/scan_cron.php`. Make sure the selected account can also write to the log directory. Task state files and worker locks prevent the same IP range from being submitted more than once at a time. + +### Test the Cron Entry Point Manually + +```bash +# Select apache or www-data for your environment and replace the module path +sudo -u apache /usr/bin/php /usr/share/zabbix/modules/zabbix_ipam/cli/scan_cron.php +``` + +No command output and a new entry on the Task Management page usually indicate a successful run. Errors are written to standard error. + +## Pages + +- **IP Management**: Add and maintain IP ranges, start scans, view scan tasks, and open the IP usage matrix +- **IP Details**: Filter all addresses by keyword, IP range, IP status, and host association status +- **Task Management**: View pending, running, completed, failed, or stopped background scan tasks + +Click **Alive IPs / Total** to open the IP usage matrix. Green indicates that an address was reachable during the latest ICMP scan; gray indicates that it was unreachable or has not yet been scanned. If a green address is associated with a Zabbix host, click it to open that host's latest data page. + +## Important Notes + +- **Authorization**: Scan only networks you are authorized to scan. +- **Address limits**: Only IPv4 is supported, with a maximum of 65,536 addresses per range. +- **Filesystem permissions**: The Zabbix Web and cron users must be able to write to the module's `data/` directory. +- **ICMP permissions**: Make sure the server firewall permits ICMP and that `fping` can run successfully. +- **Command execution**: Manual Web scans depend on PHP `exec()`; cron scans do not rely on a Web request to start a background process. +- **Performance**: Large ranges are processed in shards, with a default maximum of four parallel worker processes. +- **Host matching**: Associations are derived from the Zabbix host interfaces accessible to the current user. +- **Data storage**: Data is currently stored in JSON files. Back up the `data/` directory regularly in production. + +## Troubleshooting + +- **A scan fails immediately after clicking Start scan**: Confirm that PHP CLI exists, PHP `exec()` is enabled, and `data/scan_tasks/` is writable. +- **Every address is reported as unreachable**: Run `fping` directly as the Web or cron user and verify its installation path, execute permissions, firewall rules, and ICMP policy. The module checks `/usr/sbin/fping`, `/usr/bin/fping`, and `/sbin/fping`, in that order. +- **A task remains pending**: Check `data/scan_tasks/.log`, the PHP CLI path, and any SELinux or AppArmor restrictions. +- **Cron does not create a task**: Confirm that the IP range is enabled and that the same range does not already have a `pending` or `running` task. +- **An IP range cannot be saved**: Check ownership and permissions for `data/`. The module must be able to create lock files and temporary JSON files. +- **An address is not associated with a host**: Confirm that a Zabbix host interface uses the exact same IPv4 address and that the current user has permission to view that host. + +## Development + +The module is built on the Zabbix module framework. Its main files are: + +- `manifest.json`: Module metadata and page routes +- `Module.php`: Inventory menu registration +- `actions/IpManager.php`: IP range list business logic +- `actions/IpDetail.php`: IP details, host association filters, and pagination +- `actions/IpScan.php`: Scan task list business logic +- `actions/IpAjax.php`: AJAX endpoints for saving, deleting, scanning, and the IP matrix +- `views/ip.manager.php`: IP Management page +- `views/ip.detail.php`: IP Details page +- `views/ip.scan.php`: Task Management page +- `lib/HostMatcher.php`: Zabbix host interface IP matching +- `lib/IpScanner.php`: ICMP scanning, sharding, and multiprocessing core +- `lib/IpStorage.php`: JSON data storage +- `lib/TaskManager.php`: Background tasks and scheduled scan management +- `lib/LanguageManager.php`: Chinese and English language management +- `lib/ViewRenderer.php`: View rendering +- `lib/ZabbixVersion.php`: Zabbix version compatibility detection +- `assets/`: Page styles and client-side scripts +- `cli/scan_cron.php`: Cron scan entry point + +For extension and module development details, see the [Zabbix module development documentation](https://www.zabbix.com/documentation/7.0/en/devel/modules). + +## License + +This project follows the Zabbix licensing terms. See the [Zabbix license](https://www.zabbix.com/license) for details.