VFS_SHADOW_COPY2(8)

📦
version 4.24.7 · 27 versions
, in ubuntu stonking

💖 VFS_SHADOW_COPY2 💖

okay bestie, welcome to the vfs_shadow_copy2 page from the samba System Administration tools, and no cap this one is a whole moment. let's get into it ✨

🎀 NAME 🎀

vfs_shadow_copy2 — expose snapshots to Windows clients as shadow copies. it's giving time travel but for file shares 🦋

✨ SYNOPSIS ✨

vfs objects = shadow_copy2

💅 DESCRIPTION 💅

so this VFS module is part of the samba(7) suite, right? and what it does is basically Microsoft Shadow Copy services energy. when you set it up properly, it lets Microsoft Shadow Copy clients browse through your file system snapshots as "shadow copies" on Samba shares. iconic behavior, honestly 👑

this is the second implementation of a shadow copy module, and compared to the original shadow_copy(8) module it comes with these extra features, and bestie they ate:

  1. no need anymore to populate your share's root directory with symlinks to the snapshots if the file system stores the snapshots elsewhere. instead, you can flexibly configure the module where to look for the file system snapshots. this is highkey important when you've got thousands of shares, or you use [homes]. 😌
  2. snapshot directories don't need to be in one fixed central place — they can live anywhere in the directory tree. this mode helps support file systems that offer snapshotting of particular subtrees, like the GPFS independent file sets. very demure, very mindful 🌸
  3. vanity naming for snapshots: snapshots can be named in any format compatible with str[fp]time conversions. name them whatever, the module gets it 💅
  4. timestamps can be represented in localtime rather than UTC. your timezone, your rules 🕐
  5. the inode number of the files can optionally be altered to be different from the original. this fixes the 'restore' button in the Windows GUI so it works without a sharing violation when serving from file systems — like GPFS — that return the same device and inode number for the snapshot file and the original. literally the fix we needed 🛠️
  6. shadow copy results are by default sorted before being sent to the client. this is beneficial for filesystems that don't read directories alphabetically (the default unix). sort ordering can be configured, and sorting can be turned off completely if the file system sorts its own directory listing. customize your vibe 🎀
this module is stackable. stack it, bestie, go off 🫶

🌈 CONFIGURATION 🌈

vfs_shadow_copy2 relies on a filesystem snapshot implementation, so you need one of those first. many common filesystems have native support for this — check yours before you start anything, fr fr 👀

filesystem snapshots must be available under specially named directories in order to be recognized by vfs_shadow_copy2. this snapshot directory is typically a direct subdirectory of the share root's mountpoint, but there are other modes you can configure with the parameters described in detail below. so many options, we love options 😭

the snapshot at a given point in time is expected in a subdirectory of the snapshot directory, where the snapshot's directory is expected to be a formatted version of the snapshot time. the default format — which you can change with the shadow:format option — is @GMT-YYYY.MM.DD-hh.mm.ss, where:

  • YYYY is the 4 digit year
  • MM is the 2 digit month
  • DD is the 2 digit day
  • hh is the 2 digit hour
  • mm is the 2 digit minute
  • ss is the 2 digit second.

the vfs_shadow_copy2 snapshot naming convention can be produced with the following date(1) command:

TZ=GMT date +@GMT-%Y.%m.%d-%H.%M.%S

run it, screenshot it, live your truth 🕰️✨

✨ OPTIONS ✨

okay bestie this is the part where we meet all the knobs and dials 💅 every single one is a shadow:something parameter, and yes we're going through ALL of them, no skipping, no "eh you get the vibe" — because each one does a real thing and you deserve to know all of it 🫶

  • shadow:mountpoint = MOUNTPOINT — this one lets you state the mount point of the filesystem that holds the share path, so like, point at it yourself instead of vibing. Usually this mount point gets detected automatically ✨ but for some constellations — especially tests — it's lowkey convenient to be able to just say it out loud.

Example: shadow:mountpoint = /path/to/filesystem

Default: shadow:mountpoint = NOT SPECIFIED

  • shadow:snapdir = SNAPDIR — the path to the directory where the filesystem of the share keeps its snapshots 📁 if you hand it an absolute path, it uses it as-is, fr fr. If you hand it a relative path, then it's taken relative to the mount point of the filesystem of the share root (peep shadow:mountpoint for that one).

Heads up: shadow:snapdirseverywhere depends on this parameter and needs a relative path. Setting an absolute path disables shadow:snapdirseverywhere. 😭

Also heads up: the shadow:crossmountpoints option also requires a relative snapdir. Setting an absolute path disables shadow:crossmountpoints.

Example: shadow:snapdir = /some/absolute/path

Default: shadow:snapdir = .snapshots

  • shadow:basedir = BASEDIR — the basedir option lets you specify a directory between the share's mount point and the share root, relative to which the filesystem's snapshots are taken 🎀

So for example, if

  • basedir = mountpoint/rel_basedir
  • share_root = basedir/rel_share_root
  • snapshot_path = mountpoint/snapdir or snapshot_path = snapdir if snapdir is absolute

then the snapshot of a file = mountpoint/rel_basedir/rel_share_root/rel_file at a time TIME will be found under snapshot_path/FS_GMT_TOKEN(TIME)/rel_share_root/rel_file, where FS_GMT_TOKEN(TIME) is the timestamp string belonging to TIME in the format required by the filesystem (see shadow:format).

The default for the basedir is the mount point of the filesystem of the share root (see shadow:mountpoint).

Note that the shadow:snapdirseverywhere and shadow:crossmountpoints options are incompatible with shadow:basedir and they disable the basedir setting 💀

  • shadow:snapsharepath = SNAPSHAREPATH — with this parameter you can specify the path of the share's root directory in snapshots, relative to the snapshot's root directory. It's an alternative method to shadow:basedir, and ngl it gives you greater control 👑

For example, if within each snapshot the files of the share have a path/to/share/ prefix, then shadow:snapsharepath can be set to path/to/share.

With this parameter, it is no longer assumed that a snapshot represents an image of the original filesystem or a portion of it. For example, a system could perform backups of only files contained in shares, and then expose the backup files in a logical structure:

  • share1/
  • share2/
  • .../

Note that the shadow:snapdirseverywhere and the shadow:basedir options are incompatible with shadow:snapsharepath and disable the shadow:snapsharepath setting 🙈

Example: shadow:snapsharepath = path/to/share

Default: shadow:snapsharepath = NOT SPECIFIED

  • shadow:sort = asc/desc — by default this module sorts the shadow copy data alphabetically before sending it to the client. With this parameter you can specify the sort order 💫 the possible known values are desc (descending — that's the default) and asc (ascending). And if the filesystem already lists directories alphabetically sorted, you can turn off sorting in this module by specifying any other value ✨

Example: shadow:sort = asc

Example: shadow:sort = none

Default: shadow:sort = desc

  • shadow:localtime = yes/no — optional parameter, tells us whether the snapshot names are in UTC/GMT or in local time ⏰ if it's disabled then UTC/GMT is what's expected.

shadow:localtime = no

  • shadow:format = format specification for snapshot names — optional parameter, specifies the format specification for the naming of snapshots in the filesystem. The format must be compatible with the conversion specifications recognized by str[fp]time 🎀

Default: shadow:format = "@GMT-%Y.%m.%d-%H.%M.%S"

  • shadow:sscanf = yes/no — you can use this parameter to specify that the time in the format string is given as an unsigned long integer (%lu) rather than a time strptime() can parse. The result must be a unix time_t time 🔢

Default: shadow:sscanf = no

  • shadow:fixinodes = yes/no — if you enable shadow:fixinodes, this module modifies the apparent inode number of files in the snapshot directories using a hash of the file's path 🧚 this is needed for snapshot systems where the snapshots have the same device:inode number as the original files (such as what happens with GPFS snapshots). If you don't set this option then the 'restore' button in the shadow copy UI will fail with a sharing violation 😭

Default: shadow:fixinodes = no

  • shadow:snapdirseverywhere = yes/no — if you enable shadow:snapdirseverywhere, this module looks out for snapshot directories in the current working directory and all parent directories, stopping at the mount point by default 🔍 but see shadow:crossmountpoints for how to change that behaviour.

An example where this is needed: independent filesets in IBM's GPFS, but other filesystems might support snapshotting only particular subtrees of the filesystem as well.

Note that shadow:snapdirseverywhere depends on shadow:snapdir and needs it to be a relative path. Setting an absolute snapdir path disables shadow:snapdirseverywhere 💀

Note that this option is incompatible with the shadow:basedir option and removes the shadow:basedir setting by itself.

Example: shadow:snapdirseverywhere = yes

Default: shadow:snapdirseverywhere = no

  • shadow:crossmountpoints = yes/no — this option is effective in the case of shadow:snapdirseverywhere = yes ✨ setting it makes the module not stop at the first mount point encountered when looking for snapdirs, but instead lets it search potentially all through the path instead 🕵️

An example where this is needed: independent filesets in IBM's GPFS, but other filesystems might support snapshotting only particular subtrees of the filesystem as well.

Note that shadow:crossmountpoints depends on shadow:snapdir and needs it to be a relative path. Setting an absolute snapdir path disables shadow:crossmountpoints.

Note that this option is incompatible with the shadow:basedir option and removes the shadow:basedir setting by itself.

Example: shadow:crossmountpoints = yes

Default: shadow:crossmountpoints = no

  • shadow:snapprefix — with a growing number of snapshots, filesystems need some mechanism to differentiate one set of snapshots from another, e.g. monthly, weekly, manual, special events, etc. 🌸 so these filesystems provide different ways to tag snapshots, e.g. a configurable way to name snapshots that isn't just based on time. With only shadow:format it's very difficult to filter these snapshots 😩 with this optional parameter you can specify a variable prefix component for names of the snapshot directories in the filesystem. If this parameter is set, together with the shadow:format and shadow:delimiter parameters it determines the possible names of snapshot directories in the filesystem. The option only supports Basic Regular Expression (BRE) 🧐
  • shadow:delimiter — this optional parameter is used as a delimiter between shadow:snapprefix and shadow:format ✂️ it's used only when shadow:snapprefix is set.

Default: shadow:delimiter = "_GMT"

💖 EXAMPLES 💖

add shadow copy support to user home directories, it's giving cozy 🏠:

       [homes]
    vfs objects = shadow_copy2
    shadow:snapdir = /data/snapshots
    shadow:basedir = /data/home
    shadow:sort = desc

⚠️ CAVEATS ⚠️

okay bestie, listen, this part matters, don't scroll past it 🙏

This is not a backup, archival, or version control solution. Periodt. 🚫

With Samba or Windows servers, vfs_shadow_copy2 is designed as an end-user tool only. It does not replace or enhance your backup and archival solutions, and it should in no way be considered as such 💀 additionally, if you need version control, go implement a version control system. fr fr.

📌 VERSION 📌

This man page is part of version 4.24.7-Ubuntu-4.24.7+dfsg-1ubuntu1 of the Samba suite 👑

👑 AUTHOR 👑

The original Samba software and related utilities were created by Andrew Tridgell. Samba is now developed by the Samba Team as an Open Source project, similar to the way the Linux kernel is developed ✨

okay that's the whole page, we did it, ate and left no crumbs 💅 this absolute classic dropped as part of Samba version 4.24.7-Ubuntu-4.24.7+dfsg-1ubuntu1, dated 09/13/2026, and it lives at VFS_SHADOW_COPY2(8) — go forth and snapshot responsibly, bestie 🦋🎀💖

📦 where this page comes from