1VFS_SHADOW_COPY2(8) System Administration tools VFS_SHADOW_COPY2(8)
2
6 vfs_shadow_copy2 - Expose snapshots to Windows clients as shadow
7 copies.
8
10 vfs objects = shadow_copy2
11
13 This VFS module is part of the samba(7) suite.
14 The vfs_shadow_copy2 VFS module offers a functionality similar to
16 Microsoft Shadow Copy services. When set up properly, this module
17 allows Microsoft Shadow Copy clients to browse through file system
18 snapshots as "shadow copies" on Samba shares.
19 This is a second implementation of a shadow copy module which has the
21 following additional features (compared to the original shadow_copy(8)
22 module):
23 1. There is no need any more to populate your share's root
25 directory with symlinks to the snapshots if the file system
26 stores the snapshots elsewhere. Instead, you can flexibly
27 configure the module where to look for the file system
28 snapshots. This can be very important when you have
29 thousands of shares, or use [homes].
30 2. Snapshot directories need not be in one fixed central place
32 but can be located anywhere in the directory tree. This mode
33 helps to support file systems that offer snapshotting of
34 particular subtrees, for example the GPFS independent file
35 sets.
36 3. Vanity naming for snapshots: snapshots can be named in any
38 format compatible with str[fp]time conversions.
39 4. Timestamps can be represented in localtime rather than UTC.
41 5. The inode number of the files can optionally be altered to
43 be different from the original. This fixes the 'restore'
44 button in the Windows GUI to work without a sharing
45 violation when serving from file systems, like GPFS, that
46 return the same device and inode number for the snapshot
47 file and the original.
48 6. Shadow copy results are by default sorted before being sent
50 to the client. This is beneficial for filesystems that don't
51 read directories alphabetically (the default unix). Sort
52 ordering can be configured and sorting can be turned off
53 completely if the file system sorts its directory listing.
54 This module is stackable.
57
59 vfs_shadow_copy2 relies on a filesystem snapshot implementation. Many
60 common filesystems have native support for this.
61 Filesystem snapshots must be available under specially named
63 directories in order to be recognized by vfs_shadow_copy2. These
64 snapshot directory is typically a direct subdirectory of the share
65 root's mountpoint but there are other modes that can be configured with
66 the parameters described in detail below.
67 The snapshot at a given point in time is expected in a subdirectory of
69 the snapshot directory where the snapshot's directory is expected to be
70 a formatted version of the snapshot time. The default format which can
71 be changed with the shadow:format option is @GMT-YYYY.MM.DD-hh.mm.ss,
72 where:
73 • YYYY is the 4 digit year
75 • MM is the 2 digit month
77 • DD is the 2 digit day
79 • hh is the 2 digit hour
81 • mm is the 2 digit minute
83 • ss is the 2 digit second.
85 The vfs_shadow_copy2 snapshot naming convention can be produced with
88 the following date(1) command:
89 TZ=GMT date +@GMT-%Y.%m.%d-%H.%M.%S
91
94 shadow:mountpoint = MOUNTPOINT
95 With this parameter, one can specify the mount point of the
96 filesystem that contains the share path. Usually this mount point
97 is automatically detected. But for some constellations, in
98 particular tests, it can be convenient to be able to specify it.
99 Example: shadow:mountpoint = /path/to/filesystem
101 Default: shadow:mountpoint = NOT SPECIFIED
103 shadow:snapdir = SNAPDIR
105 Path to the directory where the file system of the share keeps its
106 snapshots. If an absolute path is specified, it is used as-is. If a
107 relative path is specified, then it is taken relative to the mount
108 point of the filesystem of the share root. (See shadow:mountpoint.)
109 Note that shadow:snapdirseverywhere depends on this parameter and
111 needs a relative path. Setting an absolute path disables
112 shadow:snapdirseverywhere.
113 Note that the shadow:crossmountpoints option also requires a
115 relative snapdir. Setting an absolute path disables
116 shadow:crossmountpoints.
117 Example: shadow:snapdir = /some/absolute/path
119 Default: shadow:snapdir = .snapshots
121 shadow:basedir = BASEDIR
123 The basedir option allows one to specify a directory between the
124 share's mount point and the share root, relative to which the file
125 system's snapshots are taken.
126 For example, if
128 • basedir = mountpoint/rel_basedir
130 • share_root = basedir/rel_share_root
132 • snapshot_path = mountpoint/snapdir
134 or snapshot_path = snapdir if snapdir is absolute
136 then the snapshot of a file =
138 mountpoint/rel_basedir/rel_share_root/rel_file at a time TIME will
139 be found under
140 snapshot_path/FS_GMT_TOKEN(TIME)/rel_share_root/rel_file, where
141 FS_GMT_TOKEN(TIME) is the timestamp string belonging to TIME in the
142 format required by the file system. (See shadow:format.)
143 The default for the basedir is the mount point of the file system
145 of the share root (see shadow:mountpoint).
146 Note that the shadow:snapdirseverywhere and shadow:crossmountpoints
148 options are incompatible with shadow:basedir and disable the
149 basedir setting.
150 shadow:snapsharepath = SNAPSHAREPATH
152 With this parameter, one can specify the path of the share's root
153 directory in snapshots, relative to the snapshot's root directory.
154 It is an alternative method to shadow:basedir, allowing greater
155 control.
156 For example, if within each snapshot the files of the share have a
158 path/to/share/ prefix, then shadow:snapsharepath can be set to
159 path/to/share.
160 With this parameter, it is no longer assumed that a snapshot
162 represents an image of the original file system or a portion of it.
163 For example, a system could perform backups of only files contained
164 in shares, and then expose the backup files in a logical structure:
165 • share1/
167 • share2/
169 • .../
171 Note that the shadow:snapdirseverywhere and the shadow:basedir
173 options are incompatible with shadow:snapsharepath and disable
174 shadow:snapsharepath setting.
175 Example: shadow:snapsharepath = path/to/share
177 Default: shadow:snapsharepath = NOT SPECIFIED
179 shadow:sort = asc/desc
181 By default, this module sorts the shadow copy data alphabetically
182 before sending it to the client. With this parameter, one can
183 specify the sort order. Possible known values are desc (descending,
184 the default) and asc (ascending). If the file system lists
185 directories alphabetically sorted, one can turn off sorting in this
186 module by specifying any other value.
187 Example: shadow:sort = asc
189 Example: shadow:sort = none
191 Default: shadow:sort = desc
193 shadow:localtime = yes/no
195 This is an optional parameter that indicates whether the snapshot
196 names are in UTC/GMT or in local time. If it is disabled then
197 UTC/GMT is expected.
198 shadow:localtime = no
200 shadow:format = format specification for snapshot names
202 This is an optional parameter that specifies the format
203 specification for the naming of snapshots in the file system. The
204 format must be compatible with the conversion specifications
205 recognized by str[fp]time.
206 Default: shadow:format = "@GMT-%Y.%m.%d-%H.%M.%S"
208 shadow:sscanf = yes/no
210 This parameter can be used to specify that the time in format
211 string is given as an unsigned long integer (%lu) rather than a
212 time strptime() can parse. The result must be a unix time_t time.
213 Default: shadow:sscanf = no
215 shadow:fixinodes = yes/no
217 If you enable shadow:fixinodes then this module will modify the
218 apparent inode number of files in the snapshot directories using a
219 hash of the files path. This is needed for snapshot systems where
220 the snapshots have the same device:inode number as the original
221 files (such as happens with GPFS snapshots). If you don't set this
222 option then the 'restore' button in the shadow copy UI will fail
223 with a sharing violation.
224 Default: shadow:fixinodes = no
226 shadow:snapdirseverywhere = yes/no
228 If you enable shadow:snapdirseverywhere then this module will look
229 out for snapshot directories in the current working directory and
230 all parent directories, stopping at the mount point by default. But
231 see shadow:crossmountpoints how to change that behaviour.
232 An example where this is needed are independent filesets in IBM's
234 GPFS, but other filesystems might support snapshotting only
235 particular subtrees of the filesystem as well.
236 Note that shadow:snapdirseverywhere depends on shadow:snapdir and
238 needs it to be a relative path. Setting an absolute snapdir path
239 disables shadow:snapdirseverywhere.
240 Note that this option is incompatible with the shadow:basedir
242 option and removes the shadow:basedir setting by itself.
243 Example: shadow:snapdirseverywhere = yes
245 Default: shadow:snapdirseverywhere = no
247 shadow:crossmountpoints = yes/no
249 This option is effective in the case of shadow:snapdirseverywhere =
250 yes. Setting this option makes the module not stop at the first
251 mount point encountered when looking for snapdirs, but lets it
252 search potentially all through the path instead.
253 An example where this is needed are independent filesets in IBM's
255 GPFS, but other filesystems might support snapshotting only
256 particular subtrees of the filesystem as well.
257 Note that shadow:crossmountpoints depends on shadow:snapdir and
259 needs it to be a relative path. Setting an absolute snapdir path
260 disables shadow:crossmountpoints.
261 Note that this option is incompatible with the shadow:basedir
263 option and removes the shadow:basedir setting by itself.
264 Example: shadow:crossmountpoints = yes
266 Default: shadow:crossmountpoints = no
268 shadow:snapprefix
270 With growing number of snapshots file-systems need some mechanism
271 to differentiate one set of snapshots from other, e.g. monthly,
272 weekly, manual, special events, etc. Therefore these file-systems
273 provide different ways to tag snapshots, e.g. provide a
274 configurable way to name snapshots, which is not just based on
275 time. With only shadow:format it is very difficult to filter these
276 snapshots. With this optional parameter, one can specify a variable
277 prefix component for names of the snapshot directories in the
278 file-system. If this parameter is set, together with the
279 shadow:format and shadow:delimiter parameters it determines the
280 possible names of snapshot directories in the file-system. The
281 option only supports Basic Regular Expression (BRE).
282 shadow:delimiter
284 This optional parameter is used as a delimiter between
285 shadow:snapprefix and shadow:format. This parameter is used only
286 when shadow:snapprefix is set.
287 Default: shadow:delimiter = "_GMT"
289
291 Add shadow copy support to user home directories:
292 [homes]
294 vfs objects = shadow_copy2
295 shadow:snapdir = /data/snapshots
296 shadow:basedir = /data/home
297 shadow:sort = desc
298
300 This is not a backup, archival, or version control solution.
301 With Samba or Windows servers, vfs_shadow_copy2 is designed to be an
303 end-user tool only. It does not replace or enhance your backup and
304 archival solutions and should in no way be considered as such.
305 Additionally, if you need version control, implement a version control
306 system.
307
309 This man page is part of version 4.16.2 of the Samba suite.
310
312 The original Samba software and related utilities were created by
313 Andrew Tridgell. Samba is now developed by the Samba Team as an Open
314 Source project similar to the way the Linux kernel is developed.
315Samba 4.16.2 06/13/2022 VFS_SHADOW_COPY2(8)