vrr/Pulse
2
0
Fork 0
mirror of https://github.com/rcourtman/Pulse.git synced 2026-10-03 04:38:48 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 17

Clarify monitoring for unregistered Proxmox ZFS pools

Browse source 
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
This commit is contained in:
pulse-triage[bot] 2026-10-01 00:24:25 +01:00
parent d80b49835c
commit cf8a3f9a6c
2 changed files with 84 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

46
docs/ZFS_MONITORING.md
View file

@ -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.

46
frontend-modern/public/docs/ZFS_MONITORING.md
View file

@ -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.