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.4</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:sort = asc/desc
 230                 </term>
 231                 <listitem>
 232                 <para>By default, this module sorts the shadow copy data
 233                 alphabetically before sending it to the client.
 234                 With this parameter, one can specify the sort order.
 235                 Possible known values are desc (descending, the default)
 236                 and asc (ascending). If the file system lists directories
 237                 alphabetically sorted, one can turn off sorting in this
 238                 module by specifying any other value.
 239                 </para>
 240                 <para>Example: shadow:sort = asc</para>
 241                 <para>Example: shadow:sort = none</para>
 242                 <para>Default: shadow:sort = desc</para>
 243                 </listitem>
 244                 </varlistentry>
 245
 246                 <varlistentry>
 247                 <term>shadow:localtime = yes/no
 248                 </term>
 249                 <listitem>
 250                 <para>This is an optional parameter that indicates whether the
 251                 snapshot names are in UTC/GMT or in local time. If it is
 252                 disabled then UTC/GMT is expected.
 253                 </para>
 254                 <para>shadow:localtime = no</para>
 255                 </listitem>
 256                 </varlistentry>
 257
 258                 <varlistentry>
 259                 <term>shadow:format = format specification for snapshot names
 260                 </term>
 261                 <listitem>
 262                 <para>This is an optional parameter that specifies the format
 263                 specification for the naming of snapshots in the file system.
 264                 The format must be compatible with the conversion
 265                 specifications recognized by str[fp]time.
 266                 </para>
 267                 <para>Default: shadow:format = "@GMT-%Y.%m.%d-%H.%M.%S"</para>
 268                 </listitem>
 269                 </varlistentry>
 270
 271                 <varlistentry>
 272                 <term>shadow:sscanf = yes/no</term>
 273                 <listitem>
 274                 <para>
 275                 This parameter can be used to specify that the time in
 276                 format string is given as an unsigned long integer (%lu)
 277                 rather than a time strptime() can parse.
 278                 The result must be a unix time_t time.
 279                 </para>
 280                 <para>Default: shadow:sscanf = no</para>
 281                 </listitem>
 282                 </varlistentry>
 283
 284                 <varlistentry>
 285                 <term>shadow:fixinodes = yes/no
 286                 </term>
 287                 <listitem>
 288                 <para>If you enable <command moreinfo="none">shadow:fixinodes
 289                 </command> then this module will modify the apparent inode
 290                 number of files in the snapshot directories using a hash of the
 291                 files path. This is needed for snapshot systems where the
 292                 snapshots have the same device:inode number as the original
 293                 files (such as happens with GPFS snapshots). If you don't set
 294                 this option then the 'restore' button in the shadow copy UI
 295                 will fail with a sharing violation.
 296                 </para>
 297                 <para>Default: shadow:fixinodes = no</para>
 298                 </listitem>
 299                 </varlistentry>
 300
 301                 <varlistentry>
 302                 <term>shadow:snapdirseverywhere = yes/no
 303                 </term>
 304                 <listitem>
 305                 <para>
 306                 If you enable
 307                 <command moreinfo="none">shadow:snapdirseverywhere </command>
 308                 then this module will look
 309                 out for snapshot directories in the current working directory
 310                 and all parent directories, stopping at the mount point
 311                 by default.
 312                 But see <command>shadow:crossmountpoints</command> how to change
 313                 that behaviour.
 314                 </para>
 315                 <para>
 316                 An example where this is needed are independent filesets in
 317                 IBM's GPFS, but other filesystems might support snapshotting
 318                 only particular subtrees of the filesystem as well.
 319                 </para>
 320                 <para>
 321                 Note that <command>shadow:snapdirseverywhere</command>
 322                 depends on <command>shadow:snapdir</command> and needs it to be
 323                 a relative path. Setting an absolute snapdir path disables
 324                 <command>shadow:snapdirseverywhere</command>.
 325                 </para>
 326                 <para>
 327                 Note that this option is incompatible with the
 328                 <command>shadow:basedir</command> option and removes the
 329                 <command>shadow:basedir</command> setting by itself.
 330                 </para>
 331                 <para>Example: shadow:snapdirseverywhere = yes</para>
 332                 <para>Default: shadow:snapdirseverywhere = no</para>
 333                 </listitem>
 334                 </varlistentry>
 335
 336                 <varlistentry>
 337                 <term>shadow:crossmountpoints = yes/no
 338                 </term>
 339                 <listitem>
 340                 <para>
 341                 This option is effective in the case of
 342                 <command>shadow:snapdirseverywhere = yes</command>.
 343                 Setting this option makes the module not stop at the
 344                 first mount point encountered when looking for snapdirs,
 345                 but lets it search potentially all through the path
 346                 instead.
 347                 </para>
 348                 <para>
 349                 An example where this is needed are independent filesets in
 350                 IBM's GPFS, but other filesystems might support snapshotting
 351                 only particular subtrees of the filesystem as well.
 352                 </para>
 353                 <para>
 354                 Note that <command>shadow:crossmountpoints</command>
 355                 depends on <command>shadow:snapdir</command> and needs it to be
 356                 a relative path. Setting an absolute snapdir path disables
 357                 <command>shadow:crossmountpoints</command>.
 358                 </para>
 359                 <para>
 360                 Note that this option is incompatible with the
 361                 <command>shadow:basedir</command> option and removes the
 362                 <command>shadow:basedir</command> setting by itself.
 363                 </para>
 364                 <para>Example: shadow:crossmountpoints = yes</para>
 365                 <para>Default: shadow:crossmountpoints = no</para>
 366                 </listitem>
 367                 </varlistentry>
 368
 369                 </variablelist>
 370 </refsect1>
 371
 372 <refsect1>
 373         <title>EXAMPLES</title>
 374
 375         <para>Add shadow copy support to user home directories:</para>
 376 <programlisting>
 377         <smbconfsection name="[homes]"/>
 378         <smbconfoption name="vfs objects">shadow_copy2</smbconfoption>
 379         <smbconfoption name="shadow:snapdir">/data/snapshots</smbconfoption>
 380         <smbconfoption name="shadow:basedir">/data/home</smbconfoption>
 381         <smbconfoption name="shadow:sort">desc</smbconfoption>
 382 </programlisting>
 383
 384 </refsect1>
 385
 386 <refsect1>
 387         <title>CAVEATS</title>
 388
 389         <para>This is not a backup, archival, or version control solution.
 390         </para>
 391
 392         <para>With Samba or Windows servers,
 393         <command>vfs_shadow_copy2</command> is designed to be an end-user
 394         tool only. It does not replace or enhance your backup and
 395         archival solutions and should in no way be considered as
 396         such. Additionally, if you need version control, implement a
 397         version control system.</para>
 398
 399 </refsect1>
 400
 401
 402
 403 <refsect1>
 404         <title>VERSION</title>
 405
 406         <para>This man page is correct for version 4.0 of the Samba suite.
 407         </para>
 408 </refsect1>
 409
 410 <refsect1>
 411         <title>AUTHOR</title>
 412
 413         <para>The original Samba software and related utilities
 414         were created by Andrew Tridgell. Samba is now developed
 415         by the Samba Team as an Open Source project similar
 416         to the way the Linux kernel is developed.</para>
 417
 418 </refsect1>
 419
 420 </refentry>