Exposing zfs snapshot to windows previous version using samba vfs_shadow_copy2

notes.md

Exposing zfs snapshot to windows previous version using samba vfs_shadow_copy2

This was much trickier than I had originally anticipated and have spent a few hours testing.

The config from samba wiki absolutely works, but it wasn't ranked higher in search engine and it's not general enough. https://github.com/zfsonlinux/zfs-auto-snapshot/wiki/Samba

Tested on ubuntu 22.04LTS, samba 4.15.9 and windows 11.

TLDR

If you snapshot utility labels the snapshot in a format other than [wildcard][timestmap], it's unlikely that it will work. sanoid and zfsnap both have dynamic labels after the timestamp, so they won't work.

Wildcard prefix

The default names for zfs-auto-snapshot is zfs-auto-snap_[label]_%Y-%m-%d-%H%M. This is the minimal viable config.

vfs_objects = shadow_copy2
shadow:snapdir = .zfs/snapshot
shadow:snapprefix = .*
shadow:delimiter = -20
shadow:format = -%Y-%m-%d-%H%M

Optional:

shadow:snapdirseverywhere = yes

Things that don't

Don't try to get creative, shadow_copy2 is extremely particular.

• -20 works as NULL for shadow:delimiter. I haven't found anything else that worked in its place. Dashes, hypens, regex patterns, alpha only strings, quoted, empty quotes, etc etc.
• removing the leading - from shadow:format.
• Using regex anywhere besides shadow:snapprefix
• Quoting your parameter

Examples that don't work

shadow:snapprefix = zfs-auto-snap_hourly
shadow:delimiter = -
shadow:format = %Y-%m-%d-%H%M

shadow:snapprefix = zfs-auto-snap
shadow:delimiter = _hourly-
shadow:format = %Y-%m-%d-%H%M

shadow:snapprefix = zfs-auto-snap_
shadow:delimiter = hourly
shadow:format = -%Y-%m-%d-%H%M

shadow:format = .*-%Y-%m-%d-%H%M

Examples that do work

The original config from samba wiki, but won't generalize for other snapshot naming pattern.

vfs objects = shadow_copy2
shadow:snapdir = .zfs/snapshot
shadow:format = -%Y-%m-%d-%H%M
shadow:snapprefix = ^zfs-auto-snap_\(frequent\)\{0,1\}\(hourly\)\{0,1\}\(daily\)\{0,1\}\(monthly\)\{0,1\}
shadow:delimiter = -20

If you don't need regex/wildcards, then using just hard code everything in shadow:format.

vfs objects = shadow_copy2
shadow: snapdir = .zfs/snapshot
shadow: sort = desc
shadow: format = zfs-auto-snap_hourly-%Y-%m-%d-%H%M

Other notes

• sanoid uses : in the snapshot names, vfs objects = catia and some extra catia config is needed for the folders under the hidden .zfs to display properly.
• Using some of the shadow options will force you to specify another option. For example: snapprefix and snapdir. Read the manpage carefully.
• The zfs-auto-snapshot package from ubuntu installs cron jobs in /etc/cron.d, /etc/cron.hourly, and etc.

The shadow copies with samba and zfs snapshots are actually easy with snapprefix. But I had to read the shadow_copy2 source code since the documentation is IMHO so misleading to the point of being wrong.

In summary it boils down to this:

• snapprefix seems to be (almost?) irrelevant as long as it matches a substring of the whole snapshot name
• contrary to what one would assume, delimiter isn't actually used a delimiter between snapprefix and format in the source code (!!!). It is more accurately described as "left-side marker of the substring that will be extracted from the snapshot name to be used to match with shadow:format"

Taking this into account and having a snapshot list like this:

whatever@zfs-auto-snap_hourly-2024-02-08-1417
whatever@zfs-auto-snap_hourly-2024-02-08-1517
whatever@zfs-auto-snap_hourly-2024-02-08-1617
whatever@zfs-auto-snap_weekly-2024-02-08-1717
whatever@zfs-auto-snap_monthly-2024-02-08-1817
whatever@zfs-auto-snap_frequent-2024-02-08-1845
whatever@zfs-auto-snap_frequent-2024-02-08-1900
whatever@zfs-auto-snap_frequent-2024-02-08-1915
whatever@zfs-auto-snap_hourly-2024-02-08-1917
whatever@zfs-auto-snap_frequent-2024-02-08-1930

You can simply do the following and it will work (well, at least it works for me(TM) 😉). The delimiter "-20" will basically select e.g. "-2024-02-08-1930" for matching with shadow:format.

shadow:snapprefix = zfs
shadow:delimiter = -20
shadow:format = -%Y-%m-%d-%H%M

Maybe you can update your gist to reflect this :-)

thanks for the in depth investigation! Hope this is useful for any unfortunate souls that stumble upon this issue in the future.