Debian Codegraph @

upstream/opensuse-tumbleweed/man8/vfs_shadow_copy2.8

raw
1 '\" t
2 .\" Title: vfs_shadow_copy2
3 .\" Author: [see the "AUTHOR" section]
4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5 .\" Date: 05/26/2026
6 .\" Manual: System Administration tools
7 .\" Source: Samba 4.23.8-git.477.f78166bceedSUSE-oS16.9-x86_64
8 .\" Language: English
9 .\"
10 .TH "VFS_SHADOW_COPY2" "8" "05/26/2026" "Samba 4\&.23\&.8\-git\&.477\&.f78166bcee" "System Administration tools"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 vfs_shadow_copy2 \- Expose snapshots to Windows clients as shadow copies\&.
32 .SH "SYNOPSIS"
33 .HP \w'\ 'u
34 vfs objects = shadow_copy2
35 .SH "DESCRIPTION"
36 .PP
37 This VFS module is part of the
38 \fBsamba\fR(7)
39 suite\&.
40 .PP
41 The
42 vfs_shadow_copy2
43 VFS module offers a functionality similar to Microsoft Shadow Copy services\&. When set up properly, this module allows Microsoft Shadow Copy clients to browse through file system snapshots as "shadow copies" on Samba shares\&.
44 .PP
45 This is a second implementation of a shadow copy module which has the following additional features (compared to the original
46 \fBshadow_copy\fR(8)
47 module):
48 .RS
49 .sp
50 .RS 4
51 .ie n \{\
52 \h'-04' 1.\h'+01'\c
53 .\}
54 .el \{\
55 .sp -1
56 .IP " 1." 4.2
57 .\}
58 There is no need any more to populate your share\*(Aqs 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 can be very important when you have thousands of shares, or use [homes]\&.
59 .RE
60 .sp
61 .RS 4
62 .ie n \{\
63 \h'-04' 2.\h'+01'\c
64 .\}
65 .el \{\
66 .sp -1
67 .IP " 2." 4.2
68 .\}
69 Snapshot directories need not be in one fixed central place but can be located anywhere in the directory tree\&. This mode helps to support file systems that offer snapshotting of particular subtrees, for example the GPFS independent file sets\&.
70 .RE
71 .sp
72 .RS 4
73 .ie n \{\
74 \h'-04' 3.\h'+01'\c
75 .\}
76 .el \{\
77 .sp -1
78 .IP " 3." 4.2
79 .\}
80 Vanity naming for snapshots: snapshots can be named in any format compatible with str[fp]time conversions\&.
81 .RE
82 .sp
83 .RS 4
84 .ie n \{\
85 \h'-04' 4.\h'+01'\c
86 .\}
87 .el \{\
88 .sp -1
89 .IP " 4." 4.2
90 .\}
91 Timestamps can be represented in localtime rather than UTC\&.
92 .RE
93 .sp
94 .RS 4
95 .ie n \{\
96 \h'-04' 5.\h'+01'\c
97 .\}
98 .el \{\
99 .sp -1
100 .IP " 5." 4.2
101 .\}
102 The inode number of the files can optionally be altered to be different from the original\&. This fixes the \*(Aqrestore\*(Aq button in the Windows GUI to work 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\&.
103 .RE
104 .sp
105 .RS 4
106 .ie n \{\
107 \h'-04' 6.\h'+01'\c
108 .\}
109 .el \{\
110 .sp -1
111 .IP " 6." 4.2
112 .\}
113 Shadow copy results are by default sorted before being sent to the client\&. This is beneficial for filesystems that don\*(Aqt read directories alphabetically (the default unix)\&. Sort ordering can be configured and sorting can be turned off completely if the file system sorts its directory listing\&.
114 .RE
115 .sp
116 .RE
117 .PP
118 This module is stackable\&.
119 .SH "CONFIGURATION"
120 .PP
121 vfs_shadow_copy2
122 relies on a filesystem snapshot implementation\&. Many common filesystems have native support for this\&.
123 .PP
124 Filesystem snapshots must be available under specially named directories in order to be recognized by
125 vfs_shadow_copy2\&. These snapshot directory is typically a direct subdirectory of the share root\*(Aqs mountpoint but there are other modes that can be configured with the parameters described in detail below\&.
126 .PP
127 The snapshot at a given point in time is expected in a subdirectory of the snapshot directory where the snapshot\*(Aqs directory is expected to be a formatted version of the snapshot time\&. The default format which can be changed with the
128 shadow:format
129 option is @GMT\-YYYY\&.MM\&.DD\-hh\&.mm\&.ss, where:
130 .RS
131 .sp
132 .RS 4
133 .ie n \{\
134 \h'-04'\(bu\h'+03'\c
135 .\}
136 .el \{\
137 .sp -1
138 .IP \(bu 2.3
139 .\}
140 YYYY
141 is the 4 digit year
142 .RE
143 .sp
144 .RS 4
145 .ie n \{\
146 \h'-04'\(bu\h'+03'\c
147 .\}
148 .el \{\
149 .sp -1
150 .IP \(bu 2.3
151 .\}
152 MM
153 is the 2 digit month
154 .RE
155 .sp
156 .RS 4
157 .ie n \{\
158 \h'-04'\(bu\h'+03'\c
159 .\}
160 .el \{\
161 .sp -1
162 .IP \(bu 2.3
163 .\}
164 DD
165 is the 2 digit day
166 .RE
167 .sp
168 .RS 4
169 .ie n \{\
170 \h'-04'\(bu\h'+03'\c
171 .\}
172 .el \{\
173 .sp -1
174 .IP \(bu 2.3
175 .\}
176 hh
177 is the 2 digit hour
178 .RE
179 .sp
180 .RS 4
181 .ie n \{\
182 \h'-04'\(bu\h'+03'\c
183 .\}
184 .el \{\
185 .sp -1
186 .IP \(bu 2.3
187 .\}
188 mm
189 is the 2 digit minute
190 .RE
191 .sp
192 .RS 4
193 .ie n \{\
194 \h'-04'\(bu\h'+03'\c
195 .\}
196 .el \{\
197 .sp -1
198 .IP \(bu 2.3
199 .\}
200 ss
201 is the 2 digit second\&.
202 .RE
203 .sp
204 .RE
205 .PP
206 The
207 vfs_shadow_copy2
208 snapshot naming convention can be produced with the following
209 \fBdate\fR(1)
210 command:
211 .sp
212 .if n \{\
213 .RS 4
214 .\}
215 .nf
216 TZ=GMT date +@GMT\-%Y\&.%m\&.%d\-%H\&.%M\&.%S
217 .fi
218 .if n \{\
219 .RE
220 .\}
221 .SH "OPTIONS"
222 .PP
223 shadow:mountpoint = MOUNTPOINT
224 .RS 4
225 With this parameter, one can specify the mount point of the filesystem that contains the share path\&. Usually this mount point is automatically detected\&. But for some constellations, in particular tests, it can be convenient to be able to specify it\&.
226 .sp
227 Example: shadow:mountpoint = /path/to/filesystem
228 .sp
229 Default: shadow:mountpoint = NOT SPECIFIED
230 .RE
231 .PP
232 shadow:snapdir = SNAPDIR
233 .RS 4
234 Path to the directory where the file system of the share keeps its snapshots\&. If an absolute path is specified, it is used as\-is\&. If a relative path is specified, then it is taken relative to the mount point of the filesystem of the share root\&. (See
235 shadow:mountpoint\&.)
236 .sp
237 Note that
238 shadow:snapdirseverywhere
239 depends on this parameter and needs a relative path\&. Setting an absolute path disables
240 shadow:snapdirseverywhere\&.
241 .sp
242 Note that the
243 shadow:crossmountpoints
244 option also requires a relative snapdir\&. Setting an absolute path disables
245 shadow:crossmountpoints\&.
246 .sp
247 Example: shadow:snapdir = /some/absolute/path
248 .sp
249 Default: shadow:snapdir = \&.snapshots
250 .RE
251 .PP
252 shadow:basedir = BASEDIR
253 .RS 4
254 The basedir option allows one to specify a directory between the share\*(Aqs mount point and the share root, relative to which the file system\*(Aqs snapshots are taken\&.
255 .sp
256 For example, if
257 .RS
258 .sp
259 .RS 4
260 .ie n \{\
261 \h'-04'\(bu\h'+03'\c
262 .\}
263 .el \{\
264 .sp -1
265 .IP \(bu 2.3
266 .\}
267 basedir = mountpoint/rel_basedir
268 .RE
269 .sp
270 .RS 4
271 .ie n \{\
272 \h'-04'\(bu\h'+03'\c
273 .\}
274 .el \{\
275 .sp -1
276 .IP \(bu 2.3
277 .\}
278 share_root = basedir/rel_share_root
279 .RE
280 .sp
281 .RS 4
282 .ie n \{\
283 \h'-04'\(bu\h'+03'\c
284 .\}
285 .el \{\
286 .sp -1
287 .IP \(bu 2.3
288 .\}
289 snapshot_path = mountpoint/snapdir
290 .sp
291 or
292 snapshot_path = snapdir
293 if snapdir is absolute
294 .RE
295 .sp
296 .RE
297 then the snapshot of a
298 file = mountpoint/rel_basedir/rel_share_root/rel_file
299 at a time TIME will be found under
300 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 file system\&. (See
301 shadow:format\&.)
302 .sp
303 The default for the basedir is the mount point of the file system of the share root (see
304 shadow:mountpoint)\&.
305 .sp
306 Note that the
307 shadow:snapdirseverywhere
308 and
309 shadow:crossmountpoints
310 options are incompatible with
311 shadow:basedir
312 and disable the basedir setting\&.
313 .RE
314 .PP
315 shadow:snapsharepath = SNAPSHAREPATH
316 .RS 4
317 With this parameter, one can specify the path of the share\*(Aqs root directory in snapshots, relative to the snapshot\*(Aqs root directory\&. It is an alternative method to
318 shadow:basedir, allowing greater control\&.
319 .sp
320 For example, if within each snapshot the files of the share have a
321 path/to/share/
322 prefix, then
323 shadow:snapsharepath
324 can be set to
325 path/to/share\&.
326 .sp
327 With this parameter, it is no longer assumed that a snapshot represents an image of the original file system 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:
328 .RS
329 .sp
330 .RS 4
331 .ie n \{\
332 \h'-04'\(bu\h'+03'\c
333 .\}
334 .el \{\
335 .sp -1
336 .IP \(bu 2.3
337 .\}
338 share1/
339 .RE
340 .sp
341 .RS 4
342 .ie n \{\
343 \h'-04'\(bu\h'+03'\c
344 .\}
345 .el \{\
346 .sp -1
347 .IP \(bu 2.3
348 .\}
349 share2/
350 .RE
351 .sp
352 .RS 4
353 .ie n \{\
354 \h'-04'\(bu\h'+03'\c
355 .\}
356 .el \{\
357 .sp -1
358 .IP \(bu 2.3
359 .\}
360 \&.\&.\&./
361 .RE
362 .sp
363 .RE
364 Note that the
365 shadow:snapdirseverywhere
366 and the
367 shadow:basedir
368 options are incompatible with
369 shadow:snapsharepath
370 and disable
371 shadow:snapsharepath
372 setting\&.
373 .sp
374 Example: shadow:snapsharepath = path/to/share
375 .sp
376 Default: shadow:snapsharepath = NOT SPECIFIED
377 .RE
378 .PP
379 shadow:sort = asc/desc
380 .RS 4
381 By default, this module sorts the shadow copy data alphabetically before sending it to the client\&. With this parameter, one can specify the sort order\&. Possible known values are desc (descending, the default) and asc (ascending)\&. If the file system lists directories alphabetically sorted, one can turn off sorting in this module by specifying any other value\&.
382 .sp
383 Example: shadow:sort = asc
384 .sp
385 Example: shadow:sort = none
386 .sp
387 Default: shadow:sort = desc
388 .RE
389 .PP
390 shadow:localtime = yes/no
391 .RS 4
392 This is an optional parameter that indicates whether the snapshot names are in UTC/GMT or in local time\&. If it is disabled then UTC/GMT is expected\&.
393 .sp
394 shadow:localtime = no
395 .RE
396 .PP
397 shadow:format = format specification for snapshot names
398 .RS 4
399 This is an optional parameter that specifies the format specification for the naming of snapshots in the file system\&. The format must be compatible with the conversion specifications recognized by str[fp]time\&.
400 .sp
401 Default: shadow:format = "@GMT\-%Y\&.%m\&.%d\-%H\&.%M\&.%S"
402 .RE
403 .PP
404 shadow:sscanf = yes/no
405 .RS 4
406 This parameter can be used to specify that the time in 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\&.
407 .sp
408 Default: shadow:sscanf = no
409 .RE
410 .PP
411 shadow:fixinodes = yes/no
412 .RS 4
413 If you enable
414 shadow:fixinodes
415 then this module will modify the apparent inode number of files in the snapshot directories using a hash of the files path\&. This is needed for snapshot systems where the snapshots have the same device:inode number as the original files (such as happens with GPFS snapshots)\&. If you don\*(Aqt set this option then the \*(Aqrestore\*(Aq button in the shadow copy UI will fail with a sharing violation\&.
416 .sp
417 Default: shadow:fixinodes = no
418 .RE
419 .PP
420 shadow:snapdirseverywhere = yes/no
421 .RS 4
422 If you enable
423 shadow:snapdirseverywhere
424 then this module will look out for snapshot directories in the current working directory and all parent directories, stopping at the mount point by default\&. But see
425 shadow:crossmountpoints
426 how to change that behaviour\&.
427 .sp
428 An example where this is needed are independent filesets in IBM\*(Aqs GPFS, but other filesystems might support snapshotting only particular subtrees of the filesystem as well\&.
429 .sp
430 Note that
431 shadow:snapdirseverywhere
432 depends on
433 shadow:snapdir
434 and needs it to be a relative path\&. Setting an absolute snapdir path disables
435 shadow:snapdirseverywhere\&.
436 .sp
437 Note that this option is incompatible with the
438 shadow:basedir
439 option and removes the
440 shadow:basedir
441 setting by itself\&.
442 .sp
443 Example: shadow:snapdirseverywhere = yes
444 .sp
445 Default: shadow:snapdirseverywhere = no
446 .RE
447 .PP
448 shadow:crossmountpoints = yes/no
449 .RS 4
450 This option is effective in the case of
451 shadow:snapdirseverywhere = yes\&. Setting this option makes the module not stop at the first mount point encountered when looking for snapdirs, but lets it search potentially all through the path instead\&.
452 .sp
453 An example where this is needed are independent filesets in IBM\*(Aqs GPFS, but other filesystems might support snapshotting only particular subtrees of the filesystem as well\&.
454 .sp
455 Note that
456 shadow:crossmountpoints
457 depends on
458 shadow:snapdir
459 and needs it to be a relative path\&. Setting an absolute snapdir path disables
460 shadow:crossmountpoints\&.
461 .sp
462 Note that this option is incompatible with the
463 shadow:basedir
464 option and removes the
465 shadow:basedir
466 setting by itself\&.
467 .sp
468 Example: shadow:crossmountpoints = yes
469 .sp
470 Default: shadow:crossmountpoints = no
471 .RE
472 .PP
473 shadow:snapprefix
474 .RS 4
475 With growing number of snapshots file\-systems need some mechanism to differentiate one set of snapshots from other, e\&.g\&. monthly, weekly, manual, special events, etc\&. Therefore these file\-systems provide different ways to tag snapshots, e\&.g\&. provide a configurable way to name snapshots, which is not just based on time\&. With only
476 shadow:format
477 it is very difficult to filter these snapshots\&. With this optional parameter, one can specify a variable prefix component for names of the snapshot directories in the file\-system\&. If this parameter is set, together with the
478 shadow:format
479 and
480 shadow:delimiter
481 parameters it determines the possible names of snapshot directories in the file\-system\&. The option only supports Basic Regular Expression (BRE)\&.
482 .RE
483 .PP
484 shadow:delimiter
485 .RS 4
486 This optional parameter is used as a delimiter between
487 shadow:snapprefix
488 and
489 shadow:format\&. This parameter is used only when
490 shadow:snapprefix
491 is set\&.
492 .sp
493 Default: shadow:delimiter = "_GMT"
494 .RE
495 .SH "EXAMPLES"
496 .PP
497 Add shadow copy support to user home directories:
498 .sp
499 .if n \{\
500 .RS 4
501 .\}
502 .nf
503 \fI[homes]\fR
504 \m[blue]\fBvfs objects = shadow_copy2\fR\m[]
505 \m[blue]\fBshadow:snapdir = /data/snapshots\fR\m[]
506 \m[blue]\fBshadow:basedir = /data/home\fR\m[]
507 \m[blue]\fBshadow:sort = desc\fR\m[]
508 .fi
509 .if n \{\
510 .RE
511 .\}
512 .SH "CAVEATS"
513 .PP
514 This is not a backup, archival, or version control solution\&.
515 .PP
516 With Samba or Windows servers,
517 vfs_shadow_copy2
518 is designed to be an end\-user tool only\&. It does not replace or enhance your backup and archival solutions and should in no way be considered as such\&. Additionally, if you need version control, implement a version control system\&.
519 .SH "VERSION"
520 .PP
521 This man page is part of version 4\&.23\&.8\-git\&.477\&.f78166bceedSUSE\-oS16\&.9\-x86_64 of the Samba suite\&.
522 .SH "AUTHOR"
523 .PP
524 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\&.