Organize and label your snapshots with helpful “notes”!
Did you know that you can tag your ZFS snapshots with “notes” and “comments”?
This is possible thanks to a useful, yet often overlooked feature called “User Properties”. As long as you follow the base:name
format, you can tag any snapshot with a custom property. I use this lesser-known feature to mark important milestones or reminders on particular snapshots like so:
zfs set custom:note="Write your note here" mypool/dataset@snapshot
Some real-world examples would be to “mark” certain milestones or reminders.
Milestones can be used to “bookend” a sequential batch of snapshots that you don’t want to destroy today, but have confirmed that they are low priority and nothing depends on them. These can be the “first-to-go” in situations where you need to quickly reclaim space on your pool.
You could do something like this:
zfs set custom:note="Safe to destroy from here until 2022-06-01 to save space" tank/downloads@manual_2020-01-31
zfs set custom:note="Safe to destroy from 2020-01-31 until here to save space" tank/downloads@manual_2022-06-01
If you need to reclaim a bunch of space on your pool, you’ll know that you can issue a batch deletion between the aforementioned snapshots above.
For a quick review of all snapshots with custom notes, you can use zfs get
to list them:
zfs get -t snap -r -s local custom:note
You can also narrow it down to only a specific pool or dataset, without searching recursively:
zfs get -t snap -s local custom:note tank/downloads
You will see output that appears like this:
tank/downloads@manual_2020-01-31 custom:note Safe to destroy from here until 2022-06-01 to save space local
tank/downloads@manual_2022-06-01 custom:note Safe to destroy from 2020-01-31 until here to save space local
The other real-world example could be used to mark certain reminders, such as searching through snapshots for a deleted file that you believe existed in January 2021. Maybe you don’t remember the filename, but have an idea of where to look.
So you do this:
zfs set custom:note="DID NOT CHECK HERE YET" tank/archives@auto_2021-01-01
zfs set custom:note="DID NOT CHECK HERE YET" tank/archives@auto_2021-01-07
zfs set custom:note="DID NOT CHECK HERE YET" tank/archives@auto_2021-01-14
zfs set custom:note="DID NOT CHECK HERE YET" tank/archives@auto_2021-01-21
zfs set custom:note="DID NOT CHECK HERE YET" tank/archives@auto_2021-01-28
Then as you confidently finish thoroughly checking each one, you can update the note:
zfs set custom:note="Nothing found" tank/archives@auto_2021-01-01
zfs set custom:note="Nothing found" tank/archives@auto_2021-01-07
And thus, your “report” will look something like this:
zfs get -t snap -s local custom:note tank/archives
tank/archives@auto_2021-01-01 custom:note Nothing found local
tank/archives@auto_2021-01-07 custom:note Nothing found local
tank/archives@auto_2021-01-14 custom:note DID NOT CHECK HERE YET local
tank/archives@auto_2021-01-21 custom:note DID NOT CHECK HERE YET local
tank/archives@auto_2021-01-28 custom:note DID NOT CHECK HERE YET local
Final thoughts and caveats
Keep in mind that these “User Properties” (i.e, “custom notes”) are always visible. Not even ZFS encryption will hide them. Try to avoid using sensitive or identifiable words. (Perhaps use “coded” language or abbreviations that only you will understand?)
To “remove” a note outright, you need to “inherit” the “User Property”. This will essentially “inherit” the dataset’s property (which doesn’t exist), and thus the snapshot will no longer have this property either.
For example, to remove a custom note:
zfs inherit custom:note tank/archives@auto_2021-01-01
For the reason above, it’s best practice to avoid setting custom notes on datasets. Only use them for snapshots. (Otherwise, every snapshot by default will “inherit” the custom note. And if you try to “remove” a note from a snapshot, it will simply re-inherit the dataset’s note.)
* Sadly, you cannot add “User Properties” (and hence “notes”) to ZFS “bookmarks”. I’m not really sure why. Perhaps it’s a worthwhile feature request for the OpenZFS GitHub?
Testimonials
“Wow!!! I never knew about this AMAZING feature with ZFS! I’ve increased my productivity by 12.7%. Thanks, Winnie!”
-Kris Moore
“I don’t see what the big deal is. Can’t you just use a text file to keep notes? This seems pointless.”
-danb35
“You really shouldn’t fabricate quotes. It could land you into legal trouble.”
-Patrick M. Hausen
“Does this feature work in Italy?”
-Davvo
“Probably my favorite feature of ZFS. Whoever wrote this resource is a real champion!”
-Winnie Linnie