infra-storage-check-zpools

Monitors ZFS pool health, runs scrubs, and sends email alerts via JSON status parsing.

1|Updated Jun 23, 2026
One-click install
npx skills add https://github.com/bitranox/bitranox-skills --skill infra-storage-check-zpools-bitranox
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: infra-storage-check-zpools
Source: https://github.com/bitranox/bitranox-skills/tree/main/plugins/bitranox/skills/infra-storage-check-zpools
Command: npx skills add https://github.com/bitranox/bitranox-skills --skill infra-storage-check-zpools-bitranox

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Hand-rolled ZFS monitoring - parsing zpool status text output, writing scrub-plus-sleep shell loops, or cron jobs that grep for errors - is fragile and misses edge cases like resilvers, faulted devices under redundancy, and deduplicated alerting. This Skill provides a complete monitoring tool that reads structured JSON output, checks thresholds, emails alerts, and runs as a systemd daemon. ## Core Features & Use Cases - Pool health checking: Reads zpool status -j --json-int (never scrapes text), checks capacity, error counts, device faults, and scrub age against configurable thresholds, with exit codes 0/1/2 for scripting. - Scrub management: Starts or adopts scrubs per pool, skips pools held by resilvers, waits without arbitrary timeouts, and supports dry-run and per-pool selection. - Alerting and daemon mode: Sends deduplicated email alerts with recovery notices, persists alert state across restarts, and installs as a systemd service with JSON status output for watching the watcher. - Use Case: On a production storage server, install the tool into an isolated Python environment, deploy a config with capacity thresholds and SMTP settings, install the systemd daemon, and schedule a weekly scrub via cron - then poll service-status --format json from another monitor. ## Quick Start Ask the AI to check the health of all ZFS pools on this machine and report any capacity, error, or scrub-age issues using check_zpools.

Frequently Asked Questions about infra-storage-check-zpools

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I monitor ZFS pool health from a script?▼

Run check_zpools check --format json to get machine-parseable pool status, and branch on exit codes: 0 healthy, 1 warning, 2 critical. It reads zpool status -j --json-int rather than scraping text output.

How do I schedule ZFS scrubs with a cron job?▼

Add a cron entry like 0 8 * * 0 /usr/local/bin/check_zpools scrub for a weekly run. The command adopts already-running scrubs, skips pools held by resilvers, and exits 1 if any pool was skipped or found errors.

Does check_zpools work on FreeBSD or macOS?▼

Yes, anywhere OpenZFS 2.3 or newer provides the zpool status -j JSON interface, including FreeBSD and OpenZFS on macOS. Only service-install (systemd) and alias-create are Linux-specific; use cron or launchd elsewhere.

Why does check_zpools fail with ZFSNotAvailableError?▼

This error means the zpool command is missing or the host runs OpenZFS older than 2.3, which lacks the -j JSON flag. Verify with zpool status -j > /dev/null; on older versions every pool-touching subcommand exits non-zero.

How do I keep SMTP passwords out of the ZFS monitoring config file?▼

Set them as environment variables using the pattern CHECK_ZPOOLS___EMAIL__SMTP_PASSWORD, which overrides the config file in the layered configuration. Config layers merge from defaults through app, host, user, .env, and environment.

When should I not use check_zpools for ZFS monitoring?▼

Avoid it on hosts without OpenZFS 2.3+, since the JSON interface it depends on does not exist there. It is also unnecessary if you only need a one-off manual status glance rather than thresholded, alerting-capable monitoring.