FreeBSD ZFS Checkpoints how to

February 22, 2026

Before we start talking about ZFS Checkpoints, if you are new to ZFS, please read the ZFS (Zettabyte File System) basics

What Is a ZFS Checkpoint

ZFS checkpoints will create a full save point for the whole pool. It is not a snapshot. It is not a bookmark.
A checkpoint freezes the entire pool state at one moment:

  • all datasets
  • all properties
  • all blocks
  • all changes

It is like a “safe restore point” before you do risky work.

Why Checkpoints Exist

Checkpoints are made for dangerous operations, for example:

  • adding or removing vdevs
  • changing pool layout
  • testing new ZFS features
  • moving data between disks
  • Big pool changes that you cannot undo with snapshots

If something goes wrong, you can roll back the whole pool.
Snapshots cannot do this. Snapshots only work on datasets. Checkpoints work on everything.

What a Checkpoint Is NOT

Plain English, no confusion:

  • Not a snapshot. Snapshots work on datasets. A checkpoint covers the whole pool.
  • Not a backup. If the pool dies, the checkpoint dies with it.
  • Not a daily tool. You use it only before risky operations, not every day.
  • Not a performance feature. It does not make the pool faster or safer during normal use.
  • Not something you keep forever. A checkpoint blocks pool changes until you delete it.

In short: A ZFS checkpoint is a temporary safety net, not a long‑term storage feature.

How To Create a Checkpoint

Here is an example of how to list, create, and verify ifa  checkpoint exists:

root@OF:~ # zpool list
NAME          SIZE  ALLOC   FREE  CKPOINT  EXPANDSZ   FRAG    CAP  DEDUP    HEALTH  ALTROOT
glacer       1.81T  4.80M  1.81T        -         -     0%     0%  1.00x    ONLINE  -
scratchpool  1.81T  7.92M  1.81T        -         -     0%     0%  1.76x    ONLINE  -
zroot         928G  34.4G   894G        -         -     6%     3%  1.00x    ONLINE  -
root@OF:~ # zpool checkpoint scratchpool
root@OF:~ # zpool status scratchpool
  pool: scratchpool
 state: ONLINE
checkpoint: created Sun Feb 22 09:04:19 2026, consumes 588K
config:

        NAME         STATE     READ WRITE CKSUM
        scratchpool  ONLINE       0     0     0
          nda1       ONLINE       0     0     0

errors: No known data errors
root@OF:~ #

 

How To Roll Back a Checkpoint in FreeBSD

Plain English, simple truth:

FreeBSD does not support checkpoint rollback. The command:

root@OF:~ # zpool checkpoint -r scratchpool
invalid option 'r'
usage:
checkpoint [-d [-w]] <pool> ...
root@OF:~ #

works on Linux/OpenZFS, but not on FreeBSD. FreeBSD ZFS only supports:

  • create checkpoint
  • list checkpoint
  • delete checkpoint

No rollback.

This is a FreeBSD design choice. Rollback was removed because it can overwrite live changes and cause corruption.

So, How Do You Roll Back on FreeBSD? (TXG Method)

FreeBSD users can still “go back in time”, but only with a TXG import.
Steps:

  1. Export the pool: 
    zpool export <pool>
  2. Import the pool at an older TXG: 
    zpool import -T <txg_number> <pool>
  3. Find TXG numbers with: 
    root@OF:~ # zpool history scratchpool
History for 'scratchpool':
2025-11-09.09:14:38 zpool create scratchpool /dev/nda1
2025-11-09.09:16:13 zfs set mountpoint=/data scratchpool
2025-11-09.09:16:19 zfs set compression=lz4 scratchpool
2025-11-09.09:16:58 zfs set dedup=on scratchpool
2026-02-09.19:34:06 zfs create scratchpool/pgsql
2026-02-09.19:34:18 zfs set mountpoint=/data/pgsql scratchpool/pgsql
2026-02-09.20:43:58 zfs create -o mountpoint=/data/redis scratchpool/redis
2026-02-22.09:04:19 zpool checkpoint scratchpool

This is the only rollback method FreeBSD supports.
It is manual, but it works.

Important Limits:
  • Only one checkpoint per pool
  • While a checkpoint exists, you cannot add or remove vdevs
  • It uses space until you delete it
  • It is not a backup
  • Rollback removes all changes after the checkpoint

Checkpoint = safety net, not a daily tool.

When To Use a Checkpoint

Use it before:

  • changing vdev layout
  • Adding new disks
  • testing new ZFS features
  • reorganizing datasets
  • doing anything that feels risky

If you ever think: “What if this breaks?” → Make a checkpoint.

Conclusion

ZFS checkpoints give you:

  • a full pool restore point
  • simple commands
  • strong safety for dangerous operations
  • peace of mind during big changes

Short, clean, and useful for any ZFS cluster
ZFS checkpoints are useful when you need a full pool save point on FreeBSD.

For more info, you can always check the official FreeBSD documentation