$RodHat_/search
Console Tips

zfs diff tells you exactly what changed since the snapshot

Published by

This article may contain Amazon affiliate links. I may earn a commission if you buy through them. Disclosure.

Terminal showing zfs diff output with plus, minus, M and R change markers beside file paths
AI illustration: RodHat
On this page · 5 sections
  1. The basic form
  2. The flags worth knowing
  3. Counting the damage
  4. What it costs
  5. Where it earns its keep

Somebody says “something changed on that box last night.” You have snapshots. You have a pile of find -newer guesses. You also have zfs diff, which reads the difference straight out of the filesystem’s own bookkeeping and hands you a list. I see people recover from snapshots for years without knowing it exists.

The basic form

zfs diff tank/data@monday tank/data@tuesday

Output is one line per changed object, a single-character change type, then the path:

M       /tank/data/
+       /tank/data/new-report.txt
-       /tank/data/old-report.txt
M       /tank/data/config.conf
R       /tank/data/draft.txt -> /tank/data/final.txt

+ created, - removed, M modified, R renamed. A directory shows up as M when entries were added or removed inside it, so do not read that line as the directory’s own contents being edited.

Leave off the second argument and it compares the snapshot to the live filesystem, which is the form I use most:

zfs diff tank/data@before-upgrade

That is “what did I just do to this dataset”, answered precisely.

The flags worth knowing

zfs diff -FHt tank/data@before-upgrade
  • -F adds a file type column (F regular file, / directory, @ symlink, and so on). Handy for filtering out the directory noise.
  • -t puts a timestamp first, so you can sort by when something changed.
  • -H gives tab-separated output with no human decoration, which is the one to use in scripts.

Check zfs-diff(8) on your release for the exact column order and type codes before you parse it. I am not going to hand you a regex from memory.

Counting the damage

When the question is “how bad”, do not scroll:

zfs diff -H tank/data@before-upgrade | awk '{print $1}' | sort | uniq -c

Four numbers: created, removed, modified, renamed. If a nightly job that should touch twelve files reports forty thousand modifications, you have your answer before you open a single one. For more of this style of pipeline, see comm and set operations on files.

What it costs

zfs diff has to turn object numbers into paths. On a dataset with millions of changes that is real work, and it is not instant just because snapshots are cheap. Diffing adjacent snapshots is the fast case. Diffing a snapshot from six months ago to now on a busy dataset is not. Run it on a quiet moment, and narrow to the dataset you care about rather than the pool root.

Two other limits. You need the privileges to resolve paths, so expect to run it as root or with delegated permission. And it compares snapshots of one dataset: it will not cross dataset boundaries for you, so a child dataset’s changes belong to the child.

Where it earns its keep

  • Before a rollback. zfs rollback throws away everything after the snapshot. Run the diff first and see what you are about to throw away. A rollback cannot be un-done, and I have seen a rollback eat a file someone swore they had saved.
  • After an incident. Which config files changed between the last good snapshot and the broken one? That is a two-line investigation, and it pairs well with reading what a wedged process is actually doing.
  • Replication sanity checks. If a source and a replica disagree, diff the same snapshot name on each side. This would have saved me in that mirror that was perfect and empty.
  • Selective restore. The diff tells you which paths changed. The snapshot lives under .zfs/snapshot/<name>/ in the dataset root, so you can copy single files back without rolling anything.

I came to this one late, after years of mounting snapshots side by side and running diff -r over them like an animal. Slow, noisy, and it reads every byte. The filesystem already knew the answer. More in the ZFS and storage hub and the FreeBSD and OpenBSD hub.