Pulse/docs/ZFS_MONITORING.md

💾 ZFS Pool Monitoring

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 for setup. This page covers Proxmox-native ZFS pools.

🚀 Features

• 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:

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

Pool health and device status come from the Proxmox API. Dataset inventory additionally requires a Unified Agent on the Proxmox node with read access to the local zfs command. If the command is unavailable, Pulse falls back to the mounted ZFS datasets visible to the agent.

# Grant permission manually if needed
pveum acl modify /nodes -user pulse-monitor@pve -role PVEAuditor

🔧 Configuration

ZFS monitoring is enabled by default. To disable it:

# Add to /etc/pulse/.env (systemd/LXC) or /data/.env (Docker/Kubernetes)
PULSE_DISABLE_ZFS_MONITORING=true

🚨 Alerts

Severity	Condition
Warning	Pool DEGRADED or any read/write/checksum errors.
Critical	Pool FAULTED or UNAVAIL.

🔍 Troubleshooting

No ZFS Data?

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