Organize and label your snapshots with helpful "notes"!

Organize and label your snapshots with helpful “notes”!​

:information_source: 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. :slightly_smiling_face:


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? :wink:


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

5 Likes

I don’t know who danb35 is, but his testimonial is right on target. :wink:

3 Likes