FreeBSD ZFS Pool Checkpoints: Create, Monitor, Rewind, and Discard

A ZFS pool checkpoint records the pool’s current state so it can later be restored through the import path. It is a pool-level administrative rollback boundary, not a normal dataset snapshot, backup, or substitute for application recovery. While a checkpoint exists, the pool accumulates space that may be needed to preserve the checkpoint’s earlier state as the live pool changes.

The feature is most useful before a narrowly scoped pool operation whose consequences are difficult to reverse. Its value depends on what is changed afterward, how much free space remains, and whether the operator understands that a writable rewind discards post-checkpoint transactions. Use it only with a documented reason, an expiration owner, and a recovery test in a non-production pool.

Distinguish a pool checkpoint from a dataset snapshot

A ZFS dataset snapshot is a named point-in-time view of a dataset and its descendants. A pool checkpoint is broader: it captures the current pool state and is consumed through zpool import rewind behavior. The two mechanisms operate at different levels and have different lifecycle and rollback consequences.

Do not use a pool checkpoint as a daily retention schedule. It is a single temporary checkpoint associated with the pool, not a list of independently addressable file trees. It does not copy data to another device or protect against failure of the pool’s disks, controller, host, or site.

Before selecting this mechanism, define the exact operation that may require rollback. If the risk is a file overwrite, dataset snapshot or backup may be more appropriate. If the risk is a pool-level change, read the matching zpool command manuals and confirm the operation is compatible with an existing checkpoint.

Preflight the pool

Capture topology, health, capacity, features, and change ownership before creating the checkpoint:

zpool status -v tank
zpool list -v tank
zpool get all tank
zpool history -il tank

Replace tank with the exact pool name. Save outputs outside the pool if they are part of an incident or change record. Confirm that the pool is healthy enough for the planned operation and that a current independent backup exists.

The zpool-checkpoint(8) manual documents that a checkpoint can consume pool space and that zpool list can be used to check checkpoint space. The manual also says that some pool operations, including remove, attach, detach, split, and reguid, are prohibited while a checkpoint exists. It warns that a checkpoint can break reservation boundaries if the pool lacks free space. These effects make both remaining capacity and planned operations part of the preflight.

Do not create a checkpoint when free-space headroom is already close to a reservation or operational threshold. The exact free-space amount needed depends on the workload and subsequent writes; no static percentage guarantees safety. Monitor pool capacity and application write volume for the whole checkpoint window.

Review the planned transaction as well as the current pool health. If the operation includes a sequence of attach, detach, split, or device removal actions, a checkpoint can prevent those commands from proceeding until it is discarded. That is a design constraint, not a reason to force the operation. Either complete the change without a checkpoint under a separately reviewed recovery plan, or choose a rollback method that does not conflict with the required command sequence.

Pool reservations deserve special attention. A dataset reservation promises space to that dataset but does not reserve physical blocks against checkpoint retention. The checkpoint manual warns that reservation boundaries can be affected when the pool lacks free space. Before enabling a checkpoint, record important refreservation and reservation values, check available pool space, and agree on a stop threshold with the storage owner.

Create and track one checkpoint

Creating the checkpoint is a pool-level mutation:

zpool checkpoint tank
zpool status tank
zpool list tank

Check the command’s exit status and verify that status reports the checkpoint. Record the pool, timestamp, operator, change ticket, planned operation, rollback cutoff, free-space baseline, and expiration deadline. Assign one person or automation owner to decide whether the checkpoint is discarded or retained for the rollback window.

Do not assume that running zpool checkpoint repeatedly creates a series of named checkpoints. The operation applies to the pool’s checkpoint state. If the pool already has a checkpoint, inspect its age, purpose, and status before taking another action. Never discard an existing checkpoint without checking who owns it.

While the checkpoint remains, monitor:

zpool status -v tank
zpool list -v tank
zpool iostat -v tank 5

Use a bounded observation interval and compare with baseline. Keep an eye on free space, application latency, and any error counters. A pool status that appears healthy does not prove that checkpoint retention has no capacity risk.

Make the checkpoint window short and observable. An alert should identify the checkpointed pool and include elapsed time, free space, and recent write rate. If the operational change takes longer than planned, pause and decide whether to complete validation and discard, or abort and rewind. Leaving an unexplained checkpoint indefinitely creates a hidden future constraint on maintenance and a growing demand for free blocks.

The checkpoint is not a substitute for a change record. Capture the exact command and output, the intended change, and the validation evidence before discard. If discard fails or remains in progress, keep the maintenance window open and investigate status rather than issuing the command repeatedly. An operator should be able to tell whether the checkpoint still exists and whether its space is still retained.

Perform the guarded change and choose a recovery outcome

Carry out only the planned change. Stop if the operation is one of the commands the manual documents as incompatible with an existing checkpoint. Do not improvise a force option to bypass a checkpoint-related refusal.

If the change succeeds and the rollback window expires, discard the checkpoint deliberately:

zpool checkpoint -d -w tank
zpool status tank
zpool list tank

The -d option discards a checkpoint; -w waits until discard completes before returning according to the manual. Check status after the command and confirm that checkpoint space is no longer reported. If discard takes time, retain monitoring and do not treat command submission as completed cleanup.

If rollback is necessary, first stop writes and assess whether a read-only evaluation is required. The zpool import manual documents –rewind-to-checkpoint as the mechanism to restore checkpointed state. A writable rewind discards changes made after the checkpoint. Treat that as data loss by design, not as a harmless undo.

Before importing with a rewind option, verify exact syntax against the installed zpool-import(8) manual and the state of the pool. Where supported and appropriate, perform a read-only inspection before committing a writable rewind. Capture current pool status and logs outside the pool. A checkpoint rewind is not an application-level rollback: external databases, clients, and remote replicas may have observed writes that the local pool will discard.

Handle the consequences of a rewind

After any rewind, compare pool status, datasets, mountpoints, and service data to the known pre-change baseline. Keep affected services stopped until their own recovery procedure has been completed. If a service wrote data after the checkpoint, its local files may no longer match messages, transactions, or replicas elsewhere.

Communicate the checkpoint boundary to application and network owners. Reconcile client-visible updates, database replication, and scheduled jobs. Do not restart all services immediately just because the pool imports successfully. Confirm checksums, database recovery state, and representative reads through application tools.

If the pool is not visible for import, do not jump immediately to rewind. First identify whether the issue is device discovery, feature compatibility, an exported pool, a device fault, or the expected checkpoint state. Follow the dedicated pool-import recovery procedure and preserve evidence before using any destructive import flags.

Common operational failures

Checkpoint space rises unexpectedly when the live pool changes substantially after the checkpoint. Reduce the rollback window, avoid large writes during it, or discard after the change has been validated. Do not resolve a full pool by deleting unrelated datasets or snapshots without reviewing retention and data ownership.

A blocked attach or detach is not a random ZFS fault if a checkpoint exists; the manual explicitly documents restrictions. Inspect status and follow the planned decision: finish the protected operation, then discard, or abandon the operation and use a supported rollback path.

A successful configuration change can still be unsafe if external state advanced beyond the checkpoint. Coordinate with applications, replication systems, and users before any writable rewind. If a rollback would violate a consistency boundary, restore the application using its own backup or reconciliation procedure instead.

Do not equate a pool checkpoint with a ZFS snapshot clone or boot environment. A boot environment can make a system-root dataset selectable for a later boot; a pool checkpoint is a broader import-level rewind boundary. The recovery mechanics and side effects are different, and mixing them in one runbook can cause an operator to invoke a pool rewind when a file- or dataset-level restore was intended. State clearly which primitive the change uses and which command will reverse it.

Acceptance criteria

A checkpoint workflow is ready when the pool and change are identified, current backup and capacity are verified, blocked operations are checked, an owner and expiry are assigned, monitoring is active, read-only and writable rewind behavior are understood, and an independent test has demonstrated application recovery after rewind.

Use pool checkpoints as temporary administrative protection with explicit space and time limits. They are not snapshots for routine browsing and never replace an independent backup or application-consistent recovery plan.

Related:

Sources: