The zfsctl Book

A guide to running ZFS with zfsctl: a terminal tool that shows your pools, datasets, snapshots, disks and shares, runs your scheduled snapshots, replication and backups, and tells you when something needs attention.

How it was made

zfsctl and this book were written by fedor4445 in collaboration with Claude, an AI model by Anthropic (through Claude Code), and directed and tested by the author on real machines.

Who this is for

You run ZFS on FreeBSD, on one machine or several. The book assumes you can use a terminal and install a package. FreeBSD-specific parts (rc.conf, geom, bectl, pkg) are explained where they come up.

How to read it

Read the first five chapters in order once; after that, jump to the chapter for the part of zfsctl you are using. Every chapter has the same shape: What you will learn, the body, Try it, and Where next.

Boxes mark the things worth noticing:

Safety: said before anything that changes your data.

Limit: something you might expect that zfsctl does not do, so you are never misled.

Tip: a shortcut or a good habit.

Keys are written in backticks, like n or Enter. Commands you type are in code blocks; the ones that need root say so.

The running example

The examples follow a small home lab: one machine, the hub, runs zfsctl and holds a pool called tank; a second machine, backup, receives copies. In the screens the machines have other names (fb, fbsd16, fbsd16t1, fbsd16t2); chapter 1 says so again where it matters.

Chapters

• 01 What zfsctl is
• 02 ZFS in 15 minutes
• 03 FreeBSD for newcomers
• 04 Installing
• 05 Remote hosts and sudoers
• 06 The screen
• 07 Hosts
• 08 Pools
• 09 Datasets
• 10 Snapshots
• 11 Disks
• 12 Shares
• 13 Boot environments
• 14 Scheduled jobs
• 15 Backups
• 16 Alerts and the daily report
• 17 Recipes
• 18 Safety
• 19 Troubleshooting
• 20 Reference: keys
• 21 Reference: configuration
• 22 Reference: commands
• 23 Glossary

For the project itself (building, the full feature list) see the project README.