1VFS_SHADOW_COPY2(8)       System Administration tools      VFS_SHADOW_COPY2(8)
2
3
4

NAME

6       vfs_shadow_copy2 - Expose snapshots to Windows clients as shadow
7       copies.
8

SYNOPSIS

10       vfs objects = shadow_copy2
11

DESCRIPTION

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

CONFIGURATION

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

OPTIONS

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

EXAMPLES

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

CAVEATS

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

VERSION

309       This man page is part of version 4.16.2 of the Samba suite.
310

AUTHOR

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.16.2                      06/13/2022               VFS_SHADOW_COPY2(8)
Impressum