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 tab, in the Storage section of the technical details, which lists each mount point once the agent reports two or more. 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

Pool health and device status come from the Proxmox API and need Sys.Audit on the affected node's disk scope. Use the user, realm and token ID actually configured for that Pulse connection, not an example account. With privilege separation enabled, effective access is the intersection of user and token permissions; a working administrator session or a user-only permission listing does not test Pulse's token.

If an existing API denial identifies missing access, have the Proxmox administrator inspect both scoped ACLs and inherited permissions. Follow Check permissions for a necessary access repair in a maintenance window. Do not grant a role across all nodes, disable privilege separation, substitute an administrator token or rerun setup just to diagnose absent ZFS data. A missing unregistered-pool row is not a permission failure.

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. Agent capacity or dataset readings do not prove the API token can read pool health.

🔧 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

Start with the same Proxmox installation, node, configured storage and backing pool in Pulse and Proxmox. Repeated storage or pool names on different nodes are not one identity. Use the existing configuration and observations; do not register a pool, rename storage or recreate a connection to make them match.

• No storage row: check whether the pool backs configured Proxmox storage, using the existing Datacenter → Storage configuration and the affected node's storage view. An intentionally unregistered pool has no separate row; use the capacity and separate health paths above. A pool's existence alone does not establish that Pulse should list it.
• Storage row present, pool health absent: capacity/usage is a separate reading. Inspect the original collection error and time, if available. Only an actual access denial supports the scoped permissions check above; a green connection badge or an administrator's successful native view does not establish that Pulse's token read the pool.
• Pool health disagrees: compare the same pool's native health and device errors with Pulse's reading and last successful collection time. A retained value is not proof of a fresh read; missing health is unknown, not ONLINE. Keep established native ZFS health checks meanwhile. Do not scrub, export/import, clear errors or replace a device just to investigate a display.

If server logs are needed, use the bounded Pulse log reader for your actual deployment and original time window. For a Pulse LXC, read inside that container, not the Proxmox host; for Docker, use the container reader. Do not pipe a journal read into grep zfs: a matching partial line can mask a failed read, and an empty search does not prove collection succeeded. Do not restart Pulse, enable Debug or run diagnostics merely to collect evidence.

For a report, retain the failing surface (row, capacity, pool health or dataset inventory), time, collection path (API or agent), and relevant redacted error. Use consistent aliases for private installation, node, storage, pool and device names. Keep token secrets, full permission listings, raw logs and screenshots with private paths or serial numbers out of the public thread. A working capacity view does not resolve a pool-health failure.