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 directory
25 with symlinks to the snapshots if the file system stores the
26 snapshots elsewhere. Instead, you can flexibly configure the module
27 where to look for the file system snapshots. This can be very
28 important when you have thousands of shares, or use [homes].
29 2. Snapshot directories need not be in one fixed central place but can
31 be located anywhere in the directory tree. This mode helps to
32 support file systems that offer snapshotting of particular
33 subtrees, for example the GPFS independent file sets.
34 3. Vanity naming for snapshots: snapshots can be named in any format
36 compatible with str[fp]time conversions.
37 4. Timestamps can be represented in localtime rather than UTC.
39 5. The inode number of the files can optionally be altered to be
41 different from the original. This fixes the ´restore´ button in the
42 Windows GUI to work without a sharing violation when serving from
43 file systems, like GPFS, that return the same device and inode
44 number for the snapshot file and the original.
45 6. Shadow copy results are by default sorted before being sent to the
47 client. This is beneficial for filesystems that don´t read
48 directories alphabetically (the default unix). Sort ordering can be
49 configured and sorting can be turned off completely if the file
50 system sorts its directory listing.
51 This module is stackable.
54
56 vfs_shadow_copy2 relies on a filesystem snapshot implementation. Many
57 common filesystems have native support for this.
58 Filesystem snapshots must be available under specially named
60 directories in order to be recognized by vfs_shadow_copy2. These
61 snapshot directory is typically a direct subdirectory of the share
62 root´s mountpoint but there are other modes that can be configured with
63 the parameters described in detail below.
64 The snapshot at a given point in time is expected in a subdirectory of
66 the snapshot directory where the snapshot´s directory is expected to be
67 a formatted version of the snapshot time. The default format which can
68 be changed with the shadow:format option is @GMT-YYYY.MM.DD-hh.mm.ss,
69 where:
70 · YYYY is the 4 digit year
72 · MM is the 2 digit month
74 · DD is the 2 digit day
76 · hh is the 2 digit hour
78 · mm is the 2 digit minute
80 · ss is the 2 digit second.
82 The vfs_shadow_copy2 snapshot naming convention can be produced with
85 the following date(1) command:
86 TZ=GMT date +@GMT-%Y.%m.%d-%H.%M.%S
88
91 shadow:mountpoint = MOUNTPOINT
92 With this parameter, one can specify the mount point of the
93 filesystem that contains the share path. Usually this mount point
94 is automatically detected. But for some constellations, in
95 particular tests, it can be convenient to be able to specify it.
96 Example: shadow:mountpoint = /path/to/filesystem
98 Default: shadow:mountpoint = NOT SPECIFIED
100 shadow:snapdir = SNAPDIR
102 Path to the directory where the file system of the share keeps its
103 snapshots. If an absolute path is specified, it is used as-is. If a
104 relative path is specified, then it is taken relative to the mount
105 point of the filesystem of the share root. (See shadow:mountpoint.)
106 Note that shadow:snapdirseverywhere depends on this parameter and
108 needs a relative path. Setting an absolute path disables
109 shadow:snapdirseverywhere.
110 Note that the shadow:crossmountpoints option also requires a
112 relative snapdir. Setting an absolute path disables
113 shadow:crossmountpoints.
114 Example: shadow:snapdir = /some/absolute/path
116 Default: shadow:snapdir = .snapshots
118 shadow:basedir = BASEDIR
120 The basedir option allows to specify a directory between the
121 share´s mount point and the share root, relative to which the file
122 system´s snapshots are taken.
123 For example, if
125 · basedir = mountpoint/rel_basedir
127 · share_root = basedir/rel_share_root
129 · snapshot_path = mountpoint/snapdir
131 or snapshot_path = snapdir if snapdir is absolute
133 then the snapshot of a file =
135 mountpoint/rel_basedir/rel_share_root/rel_file at a time TIME will be
136 found under snapshot_path/FS_GMT_TOKEN(TIME)/rel_share_root/rel_file,
137 where FS_GMT_TOKEN(TIME) is the timestamp string belonging to TIME in
138 the format required by the file system. (See shadow:format.)
139 The default for the basedir is the mount point of the file system of
141 the share root (see shadow:mountpoint).
142 Note that the shadow:snapdirseverywhere and shadow:crossmountpoints
144 options are incompatible with shadow:basedir and disable the basedir
145 setting.
146 shadow:sort = asc/desc
148 By default, this module sorts the shadow copy data alphabetically
149 before sending it to the client. With this parameter, one can
150 specify the sort order. Possible known values are desc (descending,
151 the default) and asc (ascending). If the file system lists
152 directories alphabetically sorted, one can turn off sorting in this
153 module by specifying any other value.
154 Example: shadow:sort = asc
156 Example: shadow:sort = none
158 Default: shadow:sort = desc
160 shadow:localtime = yes/no
162 This is an optional parameter that indicates whether the snapshot
163 names are in UTC/GMT or in local time. If it is disabled then
164 UTC/GMT is expected.
165 shadow:localtime = no
167 shadow:format = format specification for snapshot names
169 This is an optional parameter that specifies the format
170 specification for the naming of snapshots in the file system. The
171 format must be compatible with the conversion specifications
172 recognized by str[fp]time.
173 Default: shadow:format = "@GMT-%Y.%m.%d-%H.%M.%S"
175 shadow:sscanf = yes/no
177 This paramter can be used to specify that the time in format string
178 is given as an unsigned long integer (%lu) rather than a time
179 strptime() can parse. The result must be a unix time_t time.
180 Default: shadow:sscanf = no
182 shadow:fixinodes = yes/no
184 If you enable shadow:fixinodes then this module will modify the
185 apparent inode number of files in the snapshot directories using a
186 hash of the files path. This is needed for snapshot systems where
187 the snapshots have the same device:inode number as the original
188 files (such as happens with GPFS snapshots). If you don´t set this
189 option then the ´restore´ button in the shadow copy UI will fail
190 with a sharing violation.
191 Default: shadow:fixinodes = no
193 shadow:snapdirseverywhere = yes/no
195 If you enable shadow:snapdirseverywhere then this module will look
196 out for snapshot directories in the current working directory and
197 all parent directories, stopping at the mount point by default. But
198 see shadow:crossmountpoints how to change that behaviour.
199 An example where this is needed are independent filesets in IBM´s
201 GPFS, but other filesystems might support snapshotting only
202 particular subtrees of the filesystem as well.
203 Note that shadow:snapdirseverywhere depends on shadow:snapdir and
205 needs it to be a relative path. Setting an absolute snapdir path
206 disables shadow:snapdirseverywhere.
207 Note that this option is incompatible with the shadow:basedir
209 option and removes the shadow:basedir setting by itself.
210 Example: shadow:snapdirseverywhere = yes
212 Default: shadow:snapdirseverywhere = no
214 shadow:crossmountpoints = yes/no
216 This option is effective in the case of shadow:snapdirseverywhere =
217 yes. Setting this option makes the module not stop at the first
218 mount point encountered when looking for snapdirs, but lets it
219 search potentially all through the path instead.
220 An example where this is needed are independent filesets in IBM´s
222 GPFS, but other filesystems might support snapshotting only
223 particular subtrees of the filesystem as well.
224 Note that shadow:snapdirseverywhere depends on shadow:snapdir and
226 needs it to be a relative path. Setting an absolute snapdir path
227 disables shadow:snapdirseverywhere.
228 Note that this option is incompatible with the shadow:basedir
230 option and removes the shadow:basedir setting by itself.
231 Example: shadow:crossmountpoints = yes
233 Default: shadow:crossmountpoints = no
235
237 Add shadow copy support to user home directories:
238 [homes]
240 vfs objects = shadow_copy2
241 shadow:snapdir = /data/snapshots
242 shadow:basedir = /data/home
243 shadow:sort = desc
244
246 This is not a backup, archival, or version control solution.
247 With Samba or Windows servers, vfs_shadow_copy2 is designed to be an
249 end-user tool only. It does not replace or enhance your backup and
250 archival solutions and should in no way be considered as such.
251 Additionally, if you need version control, implement a version control
252 system.
253
255 This man page is correct for version 4.0 of the Samba suite.
256
258 The original Samba software and related utilities were created by
259 Andrew Tridgell. Samba is now developed by the Samba Team as an Open
260 Source project similar to the way the Linux kernel is developed.
261Samba 4.2 06/19/2018 VFS_SHADOW_COPY2(8)