banshee/storage-collection/storage/zfs/ssh/pools

ZFS pools, by SSH

Returns, for each ZFS pool of a Linux or FreeBSD machine, its health, its used and free space, its size and fragmentation, the data errors and device errors it has seen, and how long ago its last scrub finished. Ten watches are offered, each one set on the probe.

Versions

Generic: zpool list -H -p and zpool status -p are written the same way by OpenZFS 0.8 and later, on Linux and on FreeBSD 13 and later. It serves a TrueNAS CORE or SCALE, a Proxmox VE, a FreeBSD, an Ubuntu or Debian with zfsutils-linux, so it stays at the common level. The ZFS of FreeBSD 12 and earlier is not covered: whether its zpool status takes -p is not verified.

How it works

The collector runs three commands:

zpool list -H -p -o name,size,alloc,free,cap,frag,health: one line per pool, exact numbers in bytes, separated by tabs;
zpool status -p: for each pool, its scan: line, the error counts of each device, and its errors: line;
date "+%s %z": the machine's clock, in seconds since 1970, and the offset of its local time now (+0100).

The health is the pool's, in lower case: online, degraded, faulted, offline, unavail, removed, suspended.
The used space is allocated over size, as zpool list shows its capacity; the fragmentation is returned when the pool counts it.
The data errors are those of the errors: line (12 data errors, use '-v' for a list), 0 for No known data errors.
The device errors are the sum of the read, write and checksum counts of every device of the pool, as zpool status shows them since the pool was imported or the counts cleared.
The last scrub reads finished, running, canceled, never (no scrub on record: a resilver is not a scrub) or unreadable (a scrub line in a form not read here). Its age, in days, is counted from the end written on the scan: line, in the machine's local time without its offset, to the machine's own clock: the offset of the machine now is put on that end.
Nothing is written on the target: zpool list, zpool status and date only read.

Prerequisites

An SSH account for monitoring, without write rights, that may run zpool: on Linux, OpenZFS lets any user read the pools when /dev/zfs is readable by it (it is, by default, on Ubuntu, Debian and Proxmox); on FreeBSD and TrueNAS CORE, any user may. No sudo.
The fingerprint of the server's host key, set in protocol:ssh:fingerprint (not needed when the Security settings trust the first SSH fingerprint presented).

Outputs

Name	Label	Unit	Per instance
`health`	Health	—	yes, per pool
`used-percent`	Used space	%	yes, per pool
`free`	Free space	GiB	yes, per pool
`size`	Size	GiB	yes, per pool
`fragmentation`	Fragmentation	%	yes, per pool
`data-errors`	Data errors	—	yes, per pool
`device-errors`	Device errors	—	yes, per pool
`scrub`	Last scrub	—	yes, per pool
`scrub-age`	Time since the last scrub	d	yes, per pool

Watches

Name	Title	Kind	Defaults	Checked by default
`unhealthy`	Pool not online	expected value, on `health`	warning when the health is anything but `online`	yes
`failed`	Pool failed	state to avoid, on `health`	critical on `faulted`, `unavail`, `removed`, `suspended`	yes
`used`	Used space	above a threshold, on `used-percent`	warning above 80 %, critical above 90 %	yes
`full-soon`	Full within a week	above a threshold, on `used-percent`	warning above 99 %, ahead 7 d	yes
`fragmented`	Pool fragmented	above a threshold, on `fragmentation`	warning above 70 %	no
`data-errors`	Data errors	above a threshold, on `data-errors`	critical above 0	yes
`device-errors`	Device errors	above a threshold, on `device-errors`	warning above 0	yes
`never-scrubbed`	Pool never scrubbed	state to avoid, on `scrub`	warning on `never`	yes
`scrub-old`	Scrub too old	above a threshold, on `scrub-age`	warning above 35 d	yes
`missing`	Pool missing	expected instances, on `health`	no pool named: it raises nothing until names are set on the probe	no

Limits

A machine without zpool, or without any pool, stops the collector misconfigured; so does a zpool the account may not run.
The error counts stay until an administrator clears them (zpool clear): device-errors raises until then.
While a scrub runs, or after a canceled one, the age of the previous scrub is not known: scrub-age is not returned.
The age of a scrub can be off by an hour across a change of summer time, the offset of the machine being that of now, and by more if the machine's clock or time zone changed since.
A scrub's end is read in the form zpool status writes it (on Sun Oct 11 00:36:32 2026, English month names); a scrub line in another form reads unreadable, and its age is not returned.
Not checked against a ZFS machine: the formats are those OpenZFS documents for zpool-list and zpool-status.