docs: Update doc to use absolute path for 'dedicated keytab file'
[sfrench/samba-autobuild/.git] / docs-xml / manpages / vfs_shadow_copy2.8.xml
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
3 <refentry id="vfs_shadow_copy2.8">
4
5 <refmeta>
6         <refentrytitle>vfs_shadow_copy2</refentrytitle>
7         <manvolnum>8</manvolnum>
8         <refmiscinfo class="source">Samba</refmiscinfo>
9         <refmiscinfo class="manual">System Administration tools</refmiscinfo>
10         <refmiscinfo class="version">4.6</refmiscinfo>
11 </refmeta>
12
13
14 <refnamediv>
15         <refname>vfs_shadow_copy2</refname>
16         <refpurpose>Expose snapshots to Windows clients as shadow copies.
17         </refpurpose>
18 </refnamediv>
19
20 <refsynopsisdiv>
21         <cmdsynopsis>
22                 <command>vfs objects = shadow_copy2</command>
23         </cmdsynopsis>
24 </refsynopsisdiv>
25
26 <refsect1>
27         <title>DESCRIPTION</title>
28
29         <para>This VFS module is part of the
30         <citerefentry><refentrytitle>samba</refentrytitle>
31         <manvolnum>7</manvolnum></citerefentry> suite.</para>
32
33         <para>
34         The <command>vfs_shadow_copy2</command> VFS module offers a
35         functionality similar to Microsoft Shadow Copy services.
36         When set up properly,
37         this module allows Microsoft Shadow Copy clients to browse
38         through file system snapshots as "shadow copies" on Samba shares.
39         </para>
40
41         <para>
42         This is a second implementation of a shadow copy module
43         which has the following additional features (compared to the original
44         <citerefentry><refentrytitle>shadow_copy</refentrytitle>
45         <manvolnum>8</manvolnum></citerefentry> module):
46         </para>
47         <orderedlist continuation="restarts" inheritnum="ignore" numeration="arabic">
48         <listitem><para>
49         There is no need any more to populate your share's root directory
50         with symlinks to the snapshots if the file system stores the
51         snapshots elsewhere.
52         Instead, you can flexibly configure the module where to look for
53         the file system snapshots.
54         This can be very important when you have thousands of
55         shares, or use [homes].
56         </para></listitem>
57         <listitem><para>
58         Snapshot directories need not be in one fixed central place but
59         can be located anywhere in the directory tree. This mode helps to
60         support file systems that offer snapshotting of particular
61         subtrees, for example the GPFS independent file sets.
62         </para></listitem>
63         <listitem><para>
64         Vanity naming for snapshots: snapshots can be named in any format
65         compatible with str[fp]time conversions.
66         </para></listitem>
67         <listitem><para>
68         Timestamps can be represented in localtime rather than UTC.
69         </para></listitem>
70         <listitem><para>
71         The inode number of the files can optionally be altered to be
72         different from the original. This fixes the 'restore' button
73         in the Windows GUI to work without a sharing violation when
74         serving from file systems, like GPFS, that return the same
75         device and inode number for the snapshot file and the original.
76         </para></listitem>
77         <listitem><para>
78         Shadow copy results are by default sorted before being sent to the
79         client. This is beneficial for filesystems that don't read
80         directories alphabetically (the default unix). Sort ordering can be
81         configured and sorting can be turned off completely if the file
82         system sorts its directory listing.
83         </para></listitem>
84         </orderedlist>
85
86         <para>This module is stackable.</para>
87
88 </refsect1>
89
90 <refsect1>
91         <title>CONFIGURATION</title>
92
93         <para><command>vfs_shadow_copy2</command> relies on a filesystem
94         snapshot implementation. Many common filesystems have native
95         support for this.
96         </para>
97
98         <para>Filesystem snapshots must be available under
99         specially named directories in order to be recognized by
100         <command>vfs_shadow_copy2</command>. These snapshot directory
101         is typically a direct subdirectory of the share root's mountpoint
102         but there are other modes that can be configured with the
103         parameters described in detail below.</para>
104
105         <para>The snapshot at a given point in time is expected in a
106         subdirectory of the snapshot directory where the snapshot's
107         directory is expected to be a formatted version of the
108         snapshot time. The default format which can be changed
109         with the <command>shadow:format</command> option
110         is @GMT-YYYY.MM.DD-hh.mm.ss, where:
111         <itemizedlist>
112         <listitem><para><command>YYYY</command> is the 4 digit year</para></listitem>
113         <listitem><para><command>MM</command> is the 2 digit month</para></listitem>
114         <listitem><para><command>DD</command> is the 2 digit day</para></listitem>
115         <listitem><para><command>hh</command> is the 2 digit hour</para></listitem>
116         <listitem><para><command>mm</command> is the 2 digit minute</para></listitem>
117         <listitem><para><command>ss</command> is the 2 digit second.</para></listitem>
118         </itemizedlist>
119         </para>
120
121         <para>The <command>vfs_shadow_copy2</command> snapshot naming
122         convention can be produced with the following
123         <citerefentry><refentrytitle>date</refentrytitle>
124         <manvolnum>1</manvolnum></citerefentry> command:
125         <programlisting>
126         TZ=GMT date +@GMT-%Y.%m.%d-%H.%M.%S
127         </programlisting></para>
128
129 </refsect1>
130
131 <refsect1>
132         <title>OPTIONS</title>
133
134         <variablelist>
135                 <varlistentry>
136                 <term>shadow:mountpoint = MOUNTPOINT
137                 </term>
138                 <listitem>
139                 <para>
140                 With this parameter, one can specify the mount point
141                 of the filesystem that contains the share path.
142                 Usually this mount point is automatically detected.
143                 But for some constellations, in particular tests,
144                 it can be convenient to be able to specify it.
145                 </para>
146                 <para>Example: shadow:mountpoint = /path/to/filesystem</para>
147                 <para>Default: shadow:mountpoint = NOT SPECIFIED</para>
148                 </listitem>
149                 </varlistentry>
150
151                 <varlistentry>
152                 <term>shadow:snapdir = SNAPDIR
153                 </term>
154                 <listitem>
155                 <para>
156                 Path to the directory where the file system of
157                 the share keeps its snapshots.
158                 If an absolute path is specified, it is used as-is.
159                 If a relative path is specified, then it is taken
160                 relative to the mount point of the filesystem of
161                 the share root. (See <command>shadow:mountpoint</command>.)
162                 </para>
163                 <para>
164                 Note that <command>shadow:snapdirseverywhere</command>
165                 depends on this parameter and needs a relative path.
166                 Setting an absolute path disables
167                 <command>shadow:snapdirseverywhere</command>.
168                 </para>
169                 <para>
170                 Note that the <command>shadow:crossmountpoints</command>
171                 option also requires a relative snapdir.
172                 Setting an absolute path disables
173                 <command>shadow:crossmountpoints</command>.
174                 </para>
175                 <para>Example: shadow:snapdir = /some/absolute/path</para>
176                 <para>Default: shadow:snapdir = .snapshots</para>
177                 </listitem>
178                 </varlistentry>
179
180                 <varlistentry>
181                 <term>shadow:basedir = BASEDIR
182                 </term>
183                 <listitem>
184                 <para>
185                 The basedir option allows one to specify a directory
186                 between the share's mount point and the share root,
187                 relative to which the file system's snapshots are taken.
188                 </para>
189                 <para>
190                 For example, if
191                 <itemizedlist>
192                 <listitem><para>
193                 <command>basedir = mountpoint/rel_basedir</command>
194                 </para></listitem>
195                 <listitem><para>
196                 <command>share_root = basedir/rel_share_root</command>
197                 </para></listitem>
198                 <listitem><para>
199                 <command>snapshot_path = mountpoint/snapdir</command>
200                 </para>
201                 <para>
202                 or
203                 <command>snapshot_path = snapdir</command>
204                 if snapdir is absolute
205                 </para></listitem>
206                 </itemizedlist>
207                 then the snapshot of a
208                 <command>file = mountpoint/rel_basedir/rel_share_root/rel_file</command>
209                 at a time TIME will be found under
210                 <command>snapshot_path/FS_GMT_TOKEN(TIME)/rel_share_root/rel_file</command>,
211                 where FS_GMT_TOKEN(TIME) is the timestamp string belonging
212                 to TIME in the format required by the file system.
213                 (See <command>shadow:format</command>.)
214                 </para>
215                 <para>The default for the basedir is the mount point
216                 of the file system of the share root
217                 (see <command>shadow:mountpoint</command>).
218                 </para>
219                 <para>
220                 Note that the <command>shadow:snapdirseverywhere</command>
221                 and  <command>shadow:crossmountpoints</command>
222                 options are incompatible with <command>shadow:basedir</command>
223                 and disable the basedir setting.
224                 </para>
225                 </listitem>
226                 </varlistentry>
227
228                 <varlistentry>
229                 <term>shadow:snapsharepath = SNAPSHAREPATH
230                 </term>
231                 <listitem>
232                 <para>
233                 With this parameter, one can specify the path of the share's
234                 root directory in snapshots, relative to the snapshot's
235                 root directory. It is an alternative method to
236                 <command>shadow:basedir</command>, allowing greater control.
237                 </para>
238                 <para>
239                 For example, if within each
240                 snapshot the files of the share have a
241                 <command>path/to/share/</command> prefix, then
242                 <command>shadow:snapsharepath</command> can be
243                 set to <command>path/to/share</command>.
244                 </para>
245                 <para>
246                 With this parameter, it is no longer assumed that a
247                 snapshot represents an image of the original file system or
248                 a portion of it. For example, a system could perform
249                 backups of only files contained in shares, and then
250                 expose the backup files in a logical structure:
251                 </para>
252                 <itemizedlist>
253                 <listitem><para>share1/</para></listitem>
254                 <listitem><para>share2/</para></listitem>
255                 <listitem><para>.../</para></listitem>
256                 </itemizedlist>
257                 <para>
258                 Note that the <command>shadow:snapdirseverywhere</command>
259                 and the <command>shadow:basedir</command> options
260                 are incompatible with <command>shadow:snapsharepath</command>
261                 and disable <command>shadow:snapsharepath</command> setting.
262                 </para>
263                 <para>Example: shadow:snapsharepath = path/to/share</para>
264                 <para>Default: shadow:snapsharepath = NOT SPECIFIED</para>
265                 </listitem>
266                 </varlistentry>
267
268                 <varlistentry>
269                 <term>shadow:sort = asc/desc
270                 </term>
271                 <listitem>
272                 <para>By default, this module sorts the shadow copy data
273                 alphabetically before sending it to the client.
274                 With this parameter, one can specify the sort order.
275                 Possible known values are desc (descending, the default)
276                 and asc (ascending). If the file system lists directories
277                 alphabetically sorted, one can turn off sorting in this
278                 module by specifying any other value.
279                 </para>
280                 <para>Example: shadow:sort = asc</para>
281                 <para>Example: shadow:sort = none</para>
282                 <para>Default: shadow:sort = desc</para>
283                 </listitem>
284                 </varlistentry>
285
286                 <varlistentry>
287                 <term>shadow:localtime = yes/no
288                 </term>
289                 <listitem>
290                 <para>This is an optional parameter that indicates whether the
291                 snapshot names are in UTC/GMT or in local time. If it is
292                 disabled then UTC/GMT is expected.
293                 </para>
294                 <para>shadow:localtime = no</para>
295                 </listitem>
296                 </varlistentry>
297
298                 <varlistentry>
299                 <term>shadow:format = format specification for snapshot names
300                 </term>
301                 <listitem>
302                 <para>This is an optional parameter that specifies the format
303                 specification for the naming of snapshots in the file system.
304                 The format must be compatible with the conversion
305                 specifications recognized by str[fp]time.
306                 </para>
307                 <para>Default: shadow:format = "@GMT-%Y.%m.%d-%H.%M.%S"</para>
308                 </listitem>
309                 </varlistentry>
310
311                 <varlistentry>
312                 <term>shadow:sscanf = yes/no</term>
313                 <listitem>
314                 <para>
315                 This parameter can be used to specify that the time in
316                 format string is given as an unsigned long integer (%lu)
317                 rather than a time strptime() can parse.
318                 The result must be a unix time_t time.
319                 </para>
320                 <para>Default: shadow:sscanf = no</para>
321                 </listitem>
322                 </varlistentry>
323
324                 <varlistentry>
325                 <term>shadow:fixinodes = yes/no
326                 </term>
327                 <listitem>
328                 <para>If you enable <command moreinfo="none">shadow:fixinodes
329                 </command> then this module will modify the apparent inode
330                 number of files in the snapshot directories using a hash of the
331                 files path. This is needed for snapshot systems where the
332                 snapshots have the same device:inode number as the original
333                 files (such as happens with GPFS snapshots). If you don't set
334                 this option then the 'restore' button in the shadow copy UI
335                 will fail with a sharing violation.
336                 </para>
337                 <para>Default: shadow:fixinodes = no</para>
338                 </listitem>
339                 </varlistentry>
340
341                 <varlistentry>
342                 <term>shadow:snapdirseverywhere = yes/no
343                 </term>
344                 <listitem>
345                 <para>
346                 If you enable
347                 <command moreinfo="none">shadow:snapdirseverywhere </command>
348                 then this module will look
349                 out for snapshot directories in the current working directory
350                 and all parent directories, stopping at the mount point
351                 by default.
352                 But see <command>shadow:crossmountpoints</command> how to change
353                 that behaviour.
354                 </para>
355                 <para>
356                 An example where this is needed are independent filesets in
357                 IBM's GPFS, but other filesystems might support snapshotting
358                 only particular subtrees of the filesystem as well.
359                 </para>
360                 <para>
361                 Note that <command>shadow:snapdirseverywhere</command>
362                 depends on <command>shadow:snapdir</command> and needs it to be
363                 a relative path. Setting an absolute snapdir path disables
364                 <command>shadow:snapdirseverywhere</command>.
365                 </para>
366                 <para>
367                 Note that this option is incompatible with the
368                 <command>shadow:basedir</command> option and removes the
369                 <command>shadow:basedir</command> setting by itself.
370                 </para>
371                 <para>Example: shadow:snapdirseverywhere = yes</para>
372                 <para>Default: shadow:snapdirseverywhere = no</para>
373                 </listitem>
374                 </varlistentry>
375
376                 <varlistentry>
377                 <term>shadow:crossmountpoints = yes/no
378                 </term>
379                 <listitem>
380                 <para>
381                 This option is effective in the case of
382                 <command>shadow:snapdirseverywhere = yes</command>.
383                 Setting this option makes the module not stop at the
384                 first mount point encountered when looking for snapdirs,
385                 but lets it search potentially all through the path
386                 instead.
387                 </para>
388                 <para>
389                 An example where this is needed are independent filesets in
390                 IBM's GPFS, but other filesystems might support snapshotting
391                 only particular subtrees of the filesystem as well.
392                 </para>
393                 <para>
394                 Note that <command>shadow:crossmountpoints</command>
395                 depends on <command>shadow:snapdir</command> and needs it to be
396                 a relative path. Setting an absolute snapdir path disables
397                 <command>shadow:crossmountpoints</command>.
398                 </para>
399                 <para>
400                 Note that this option is incompatible with the
401                 <command>shadow:basedir</command> option and removes the
402                 <command>shadow:basedir</command> setting by itself.
403                 </para>
404                 <para>Example: shadow:crossmountpoints = yes</para>
405                 <para>Default: shadow:crossmountpoints = no</para>
406                 </listitem>
407                 </varlistentry>
408
409                 <varlistentry>
410                 <term>shadow:snapprefix
411                 </term>
412                 <listitem>
413                 <para>
414                 With growing number of snapshots file-systems need some mechanism
415                 to differentiate one set of snapshots from other, e.g. monthly, weekly,
416                 manual, special events, etc. Therefore these file-systems provide different
417                 ways to tag snapshots, e.g. provide a configurable way to name snapshots,
418                 which is not just based on time.  With only <command>shadow:format</command>
419                 it is very difficult to filter these snapshots. With this optional parameter,
420                 one can specify a variable prefix component for names of the snapshot
421                 directories in the file-system. If this parameter is set, together with the
422                 <command>shadow:format</command> and <command>shadow:delimiter</command>
423                 parameters it determines the possible names of snapshot
424                 directories in the file-system. The option only supports Basic
425                 Regular Expression (BRE).
426                 </para>
427                 </listitem>
428                 </varlistentry>
429
430                 <varlistentry>
431                 <term>shadow:delimiter
432                 </term>
433                 <listitem>
434                 <para>
435                 This optional parameter is used as a delimiter between
436                 <command>shadow:snapprefix</command> and <command>shadow:format</command>.
437                 This parameter is used only when <command>shadow:snapprefix</command>
438                 is set.
439                 </para>
440                 <para>Default: shadow:delimiter = "_GMT"</para>
441                 </listitem>
442                 </varlistentry>
443         </variablelist>
444 </refsect1>
445
446 <refsect1>
447         <title>EXAMPLES</title>
448
449         <para>Add shadow copy support to user home directories:</para>
450 <programlisting>
451         <smbconfsection name="[homes]"/>
452         <smbconfoption name="vfs objects">shadow_copy2</smbconfoption>
453         <smbconfoption name="shadow:snapdir">/data/snapshots</smbconfoption>
454         <smbconfoption name="shadow:basedir">/data/home</smbconfoption>
455         <smbconfoption name="shadow:sort">desc</smbconfoption>
456 </programlisting>
457
458 </refsect1>
459
460 <refsect1>
461         <title>CAVEATS</title>
462
463         <para>This is not a backup, archival, or version control solution.
464         </para>
465
466         <para>With Samba or Windows servers,
467         <command>vfs_shadow_copy2</command> is designed to be an end-user
468         tool only. It does not replace or enhance your backup and
469         archival solutions and should in no way be considered as
470         such. Additionally, if you need version control, implement a
471         version control system.</para>
472
473 </refsect1>
474
475
476
477 <refsect1>
478         <title>VERSION</title>
479
480         <para>This man page is correct for version 4.0 of the Samba suite.
481         </para>
482 </refsect1>
483
484 <refsect1>
485         <title>AUTHOR</title>
486
487         <para>The original Samba software and related utilities
488         were created by Andrew Tridgell. Samba is now developed
489         by the Samba Team as an Open Source project similar
490         to the way the Linux kernel is developed.</para>
491
492 </refsect1>
493
494 </refentry>