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">&doc.version;</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 part of version &doc.version; 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>