1VFS_SHADOW_COPY2(8) System Administration tools VFS_SHADOW_COPY2(8)
2
3
4
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
15 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
20 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
24 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
31 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
37 3. Vanity naming for snapshots: snapshots can be named in any
38 format compatible with str[fp]time conversions.
39
40 4. Timestamps can be represented in localtime rather than UTC.
41
42 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
49 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
55
56 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
62 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
68 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
74 · YYYY is the 4 digit year
75
76 · MM is the 2 digit month
77
78 · DD is the 2 digit day
79
80 · hh is the 2 digit hour
81
82 · mm is the 2 digit minute
83
84 · ss is the 2 digit second.
85
86
87 The vfs_shadow_copy2 snapshot naming convention can be produced with
88 the following date(1) command:
89
90 TZ=GMT date +@GMT-%Y.%m.%d-%H.%M.%S
91
92
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
100 Example: shadow:mountpoint = /path/to/filesystem
101
102 Default: shadow:mountpoint = NOT SPECIFIED
103
104 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
110 Note that shadow:snapdirseverywhere depends on this parameter and
111 needs a relative path. Setting an absolute path disables
112 shadow:snapdirseverywhere.
113
114 Note that the shadow:crossmountpoints option also requires a
115 relative snapdir. Setting an absolute path disables
116 shadow:crossmountpoints.
117
118 Example: shadow:snapdir = /some/absolute/path
119
120 Default: shadow:snapdir = .snapshots
121
122 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
127 For example, if
128
129 · basedir = mountpoint/rel_basedir
130
131 · share_root = basedir/rel_share_root
132
133 · snapshot_path = mountpoint/snapdir
134
135 or snapshot_path = snapdir if snapdir is absolute
136
137 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
144 The default for the basedir is the mount point of the file system
145 of the share root (see shadow:mountpoint).
146
147 Note that the shadow:snapdirseverywhere and shadow:crossmountpoints
148 options are incompatible with shadow:basedir and disable the
149 basedir setting.
150
151 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
157 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
161 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
166 · share1/
167
168 · share2/
169
170 · .../
171
172 Note that the shadow:snapdirseverywhere and the shadow:basedir
173 options are incompatible with shadow:snapsharepath and disable
174 shadow:snapsharepath setting.
175
176 Example: shadow:snapsharepath = path/to/share
177
178 Default: shadow:snapsharepath = NOT SPECIFIED
179
180 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
188 Example: shadow:sort = asc
189
190 Example: shadow:sort = none
191
192 Default: shadow:sort = desc
193
194 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
199 shadow:localtime = no
200
201 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
207 Default: shadow:format = "@GMT-%Y.%m.%d-%H.%M.%S"
208
209 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
214 Default: shadow:sscanf = no
215
216 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
225 Default: shadow:fixinodes = no
226
227 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
233 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
237 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
241 Note that this option is incompatible with the shadow:basedir
242 option and removes the shadow:basedir setting by itself.
243
244 Example: shadow:snapdirseverywhere = yes
245
246 Default: shadow:snapdirseverywhere = no
247
248 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
254 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
258 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
262 Note that this option is incompatible with the shadow:basedir
263 option and removes the shadow:basedir setting by itself.
264
265 Example: shadow:crossmountpoints = yes
266
267 Default: shadow:crossmountpoints = no
268
269 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
283 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
288 Default: shadow:delimiter = "_GMT"
289
291 Add shadow copy support to user home directories:
292
293 [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
302 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.10.4 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.
315
316
317
318Samba 4.10.4 05/28/2019 VFS_SHADOW_COPY2(8)