From cf8a3f9a6cca47509efc10df62ba24bb00f9aa09 Mon Sep 17 00:00:00 2001 From: "pulse-triage[bot]" <249995291+pulse-triage[bot]@users.noreply.github.com> Date: Thu, 1 Oct 2026 00:24:25 +0100 Subject: [PATCH] Clarify monitoring for unregistered Proxmox ZFS pools Explain the configured-storage boundary, the existing agent capacity path and the separate pool-health gap. Keep data-only pools unchanged and put storage membership ahead of permission changes in troubleshooting. Change-source: pulse-maintainer --- docs/ZFS_MONITORING.md | 46 +++++++++++++++++-- frontend-modern/public/docs/ZFS_MONITORING.md | 46 +++++++++++++++++-- 2 files changed, 84 insertions(+), 8 deletions(-) diff --git a/docs/ZFS_MONITORING.md b/docs/ZFS_MONITORING.md index 97000f0b4..f3d999f22 100644 --- a/docs/ZFS_MONITORING.md +++ b/docs/ZFS_MONITORING.md @@ -1,17 +1,50 @@ # 💾 ZFS Pool Monitoring -Pulse automatically detects and monitors ZFS pools on your Proxmox nodes. +Pulse adds ZFS pool health to **configured Proxmox storage** on your nodes. +The Proxmox → Storage list is not an inventory of every local ZFS pool. > **TrueNAS users:** TrueNAS ZFS pool monitoring is handled separately via the TrueNAS integration. See [CONFIGURATION.md](CONFIGURATION.md#truenas) for setup. This page covers Proxmox-native ZFS pools. ## 🚀 Features -* **Auto-Detection**: No configuration needed. +* **Auto-Detection**: Matches configured storage to its backing ZFS pool, including directory storage on a ZFS dataset. * **Health Status**: Tracks `ONLINE`, `DEGRADED`, and `FAULTED` states. * **Error Tracking**: Monitors read, write, and checksum errors. * **Dataset Inventory**: With a Unified Agent on the node, expanded pool details list ZFS filesystems and zvols with used, available, referenced, and mountpoint information. * **Alerts**: Notifies you of degraded pools or failing devices. +## Unregistered and data-only pools + +Pulse reads `/nodes/{node}/disks/zfs` and the pool-detail endpoint to enrich +Proxmox storage rows. A pool that is not configured in `/etc/pve/storage.cfg` +does not get its own row, even if it is `ONLINE` in the ZFS API, its physical +disks are visible, and the API account has the required permissions. A pool +used only through datasets and LXC bind mounts can therefore be absent from +Proxmox → Storage without a collection error. + +Do not register a pool as Proxmox storage or change its datasets solely to make +it appear in Pulse. For a pool you intentionally keep unregistered: + +* A **Unified Agent on the Proxmox host**, with a locally mounted ZFS dataset + and access to `zpool`, can report capacity and usage in the node's + **Overview details → Disks** panel, under the selected mount point. Without + usable `zpool` output, the agent falls back to mounted-dataset counters; + those are not necessarily whole-pool capacity. +* That capacity view and physical-disk SMART data do **not** provide + `DEGRADED`/`FAULTED` pool-health alerts for an unregistered pool with no + matching Proxmox storage row. Keep a separate ZFS health check for it. +* On the Proxmox host, these read-only commands show pool capacity, health and + device errors. Replace `tank` with your pool name: + + ```bash + zpool list -o name,size,alloc,free,health tank + zpool status tank + ``` + +`zpool list` reports raw pool capacity; it can differ from the agent's usable +capacity estimate on RAIDZ. These commands do not change the pool or register +it as Proxmox storage. + ## ⚙️ Requirements The Pulse user needs `Sys.Audit` permission on `/nodes/{node}/disks` (included in the standard Pulse role). @@ -42,6 +75,11 @@ PULSE_DISABLE_ZFS_MONITORING=true ## 🔍 Troubleshooting **No ZFS Data?** -1. Check permissions: `pveum user permissions pulse-monitor@pve`. +1. Check whether the pool backs configured Proxmox storage: `pvesm status`. + If it is intentionally unregistered, use the capacity and health paths above. 2. Verify pools exist: `zpool list`. -3. Check logs: `journalctl -u pulse -n 200 | grep -i zfs`. +3. For a missing configured storage row, check permissions: + `pveum user permissions pulse-monitor@pve`. +4. Check logs: `journalctl -u pulse -n 200 | grep -i zfs`. + A missing unregistered-pool row alone is not evidence that more API + permissions are needed. diff --git a/frontend-modern/public/docs/ZFS_MONITORING.md b/frontend-modern/public/docs/ZFS_MONITORING.md index 97000f0b4..f3d999f22 100644 --- a/frontend-modern/public/docs/ZFS_MONITORING.md +++ b/frontend-modern/public/docs/ZFS_MONITORING.md @@ -1,17 +1,50 @@ # 💾 ZFS Pool Monitoring -Pulse automatically detects and monitors ZFS pools on your Proxmox nodes. +Pulse adds ZFS pool health to **configured Proxmox storage** on your nodes. +The Proxmox → Storage list is not an inventory of every local ZFS pool. > **TrueNAS users:** TrueNAS ZFS pool monitoring is handled separately via the TrueNAS integration. See [CONFIGURATION.md](CONFIGURATION.md#truenas) for setup. This page covers Proxmox-native ZFS pools. ## 🚀 Features -* **Auto-Detection**: No configuration needed. +* **Auto-Detection**: Matches configured storage to its backing ZFS pool, including directory storage on a ZFS dataset. * **Health Status**: Tracks `ONLINE`, `DEGRADED`, and `FAULTED` states. * **Error Tracking**: Monitors read, write, and checksum errors. * **Dataset Inventory**: With a Unified Agent on the node, expanded pool details list ZFS filesystems and zvols with used, available, referenced, and mountpoint information. * **Alerts**: Notifies you of degraded pools or failing devices. +## Unregistered and data-only pools + +Pulse reads `/nodes/{node}/disks/zfs` and the pool-detail endpoint to enrich +Proxmox storage rows. A pool that is not configured in `/etc/pve/storage.cfg` +does not get its own row, even if it is `ONLINE` in the ZFS API, its physical +disks are visible, and the API account has the required permissions. A pool +used only through datasets and LXC bind mounts can therefore be absent from +Proxmox → Storage without a collection error. + +Do not register a pool as Proxmox storage or change its datasets solely to make +it appear in Pulse. For a pool you intentionally keep unregistered: + +* A **Unified Agent on the Proxmox host**, with a locally mounted ZFS dataset + and access to `zpool`, can report capacity and usage in the node's + **Overview details → Disks** panel, under the selected mount point. Without + usable `zpool` output, the agent falls back to mounted-dataset counters; + those are not necessarily whole-pool capacity. +* That capacity view and physical-disk SMART data do **not** provide + `DEGRADED`/`FAULTED` pool-health alerts for an unregistered pool with no + matching Proxmox storage row. Keep a separate ZFS health check for it. +* On the Proxmox host, these read-only commands show pool capacity, health and + device errors. Replace `tank` with your pool name: + + ```bash + zpool list -o name,size,alloc,free,health tank + zpool status tank + ``` + +`zpool list` reports raw pool capacity; it can differ from the agent's usable +capacity estimate on RAIDZ. These commands do not change the pool or register +it as Proxmox storage. + ## ⚙️ Requirements The Pulse user needs `Sys.Audit` permission on `/nodes/{node}/disks` (included in the standard Pulse role). @@ -42,6 +75,11 @@ PULSE_DISABLE_ZFS_MONITORING=true ## 🔍 Troubleshooting **No ZFS Data?** -1. Check permissions: `pveum user permissions pulse-monitor@pve`. +1. Check whether the pool backs configured Proxmox storage: `pvesm status`. + If it is intentionally unregistered, use the capacity and health paths above. 2. Verify pools exist: `zpool list`. -3. Check logs: `journalctl -u pulse -n 200 | grep -i zfs`. +3. For a missing configured storage row, check permissions: + `pveum user permissions pulse-monitor@pve`. +4. Check logs: `journalctl -u pulse -n 200 | grep -i zfs`. + A missing unregistered-pool row alone is not evidence that more API + permissions are needed.