docs: update the manpage of vfs_shadow_copy2

Document the configuration and all the options
available for the shadow_copy2 module.

Pair-Programmed-With: Björn Baumbach <bb@sernet.de>

Signed-off-by: Michael Adam <obnox@samba.org>

Reviewed-by: Andrew Bartlett <abartlet@samba.org>

Autobuild-User(master): Andrew Bartlett <abartlet@samba.org>
Autobuild-Date(master): Fri Dec  6 22:26:31 CET 2013 on sn-devel-104
(cherry picked from commit f6ac6f20540f81257e1f180454b6a2c1239e85fa)

1 files changed, 242 insertions, 48 deletions

diff --git a/docs-xml/manpages/vfs_shadow_copy2.8.xml b/docs-xml/manpages/vfs_shadow_copy2.8.xml
index b313416c6b6..4f60667ae28 100644
--- a/docs-xml/manpages/vfs_shadow_copy2.8.xml
+++ b/docs-xml/manpages/vfs_shadow_copy2.8.xml
@@ -13,7 +13,8 @@
 
 <refnamediv>
 	<refname>vfs_shadow_copy2</refname>
-	<refpurpose>Expose snapshots to Windows clients as shadow copies.</refpurpose>
+	<refpurpose>Expose snapshots to Windows clients as shadow copies.
+	</refpurpose>
 </refnamediv>
 
 <refsynopsisdiv>
@@ -29,21 +30,57 @@
 	<citerefentry><refentrytitle>samba</refentrytitle>
 	<manvolnum>7</manvolnum></citerefentry> suite.</para>
 
-	<para>The <command>vfs_shadow_copy2</command> VFS module functionality
-	that is similar to Microsoft Shadow Copy services. When setup properly,
+	<para>
+	The <command>vfs_shadow_copy2</command> VFS module offers a
+	functionality similar to Microsoft Shadow Copy services.
+	When set up properly,
 	this module allows Microsoft Shadow Copy clients to browse
-	"shadow copies" on Samba shares.
+	through file system snapshots as "shadow copies" on Samba shares.
 	</para>
 
-	<para>This is a 2nd implementation of a shadow copy module. This
-	version has the following features:</para>
+	<para>
+	This is a second implementation of a shadow copy module
+	which has the following additional features (compared to the original
+	<citerefentry><refentrytitle>shadow_copy</refentrytitle>
+	<manvolnum>8</manvolnum></citerefentry> module):
+	</para>
 	<orderedlist continuation="restarts" inheritnum="ignore" numeration="arabic">
-        <listitem><para>You don't need to populate your shares with symlinks to the
-	snapshots. This can be very important when you have thousands of
-	shares, or use [homes].</para></listitem>
-	<listitem><para>The inode number of the files is altered so it is different
-	from the original. This allows the 'restore' button to work
-	without a sharing violation.</para></listitem>
+	<listitem><para>
+	There is no need any more to populate your share's root directory
+	with symlinks to the snapshots if the file system stores the
+	snapshots elsewhere.
+	Instead, you can flexibly configure the module where to look for
+	the file system snapshots.
+	This can be very important when you have thousands of
+	shares, or use [homes].
+	</para></listitem>
+	<listitem><para>
+	Snapshot directories need not be in one fixed central place but
+	can be located anywhere in the directory tree. This mode helps to
+	support file systems that offer snapshotting of particutlar
+	subtrees, for example the GPFS independent file sets.
+	</para></listitem>
+	<listitem><para>
+	Vanity naming for snapshots: snapshots can be named in any format
+	compatible with with str[fp]time conversions.
+	</para></listitem>
+	<listitem><para>
+	Timestamps can be represented in localtime rather than UTC.
+	</para></listitem>
+	<listitem><para>
+	The inode number of the files can optionally be altered to be
+	different from the original. This fixes the 'restore' button
+	in the Windows GUI to work without a sharing violation when
+	serving from file systems, like GPFS, that return the same
+	device and inode number for the snapshot file and the original.
+	</para></listitem>
+	<listitem><para>
+	Shadow copy results are by default sorted before being sent to the
+	client. This is beneficial for filesystems that don't read
+	directories alphabetically (the default unix). Sort ordering can be
+	configured and sorting can be turned off completely if the file
+	system sorts its directory listing.
+	</para></listitem>
 	</orderedlist>
 
 	<para>This module is stackable.</para>
@@ -58,25 +95,32 @@
 	support for this.
 	</para>
 
-	<para>Filesystem snapshots must be mounted on
+	<para>Filesystem snapshots must be available under
 	specially named directories in order to be recognized by
-	<command>vfs_shadow_copy2</command>. The snapshot mount points must
-	be immediate children of a the directory being shared.</para>
-
-	<para>The snapshot naming convention is @GMT-YYYY.MM.DD-hh.mm.ss,
-	where:
+	<command>vfs_shadow_copy2</command>. These snapshot directory
+	is typically a direct subdirectory of the share root's mountpoint
+	but there are other modes that can be configured with the
+	parameters described in detail below.</para>
+
+	<para>The snapshot at a given point in time is expected in a
+	subdirectory of the snapshot directory where the snapshot's
+	directory is expected to be a formatted version of the
+	snapshot time. The default format which can be changed
+	with the <command>shadow:format</command> option
+	is @GMT-YYYY.MM.DD-hh.mm.ss, where:
 	<itemizedlist>
-		<listitem><para><command>YYYY</command> is the 4 digit year</para></listitem>
-		<listitem><para><command>MM</command> is the 2 digit month</para></listitem>
-		<listitem><para><command>DD</command> is the 2 digit day</para></listitem>
-		<listitem><para><command>hh</command> is the 2 digit hour</para></listitem>
-		<listitem><para><command>mm</command> is the 2 digit minute</para></listitem>
-		<listitem><para><command>ss</command> is the 2 digit second.</para></listitem>
-		</itemizedlist>
+	<listitem><para><command>YYYY</command> is the 4 digit year</para></listitem>
+	<listitem><para><command>MM</command> is the 2 digit month</para></listitem>
+	<listitem><para><command>DD</command> is the 2 digit day</para></listitem>
+	<listitem><para><command>hh</command> is the 2 digit hour</para></listitem>
+	<listitem><para><command>mm</command> is the 2 digit minute</para></listitem>
+	<listitem><para><command>ss</command> is the 2 digit second.</para></listitem>
+	</itemizedlist>
 	</para>
 
-	<para>The <command>vfs_shadow_copy2</command> snapshot naming convention can be
-	produced with the following <citerefentry><refentrytitle>date</refentrytitle>
+	<para>The <command>vfs_shadow_copy2</command> snapshot naming
+	convention can be produced with the following
+	<citerefentry><refentrytitle>date</refentrytitle>
 	<manvolnum>1</manvolnum></citerefentry> command:
 	<programlisting>
 	TZ=GMT date +@GMT-%Y.%m.%d-%H.%M.%S
@@ -89,11 +133,47 @@
 
         <variablelist>
 		<varlistentry>
+                <term>shadow:mountpoint = MOUNTPOINT
+                </term>
+                <listitem>
+		<para>
+		With this parameter, one can specify the mount point
+		of the filesystem that contains the share path.
+		Usually this mount point is automatically detected.
+		But for some constellations, in particular tests,
+		it can be convenient to be able to specify it.
+		</para>
+		<para>Example: shadow:mountpoint = /path/to/filesystem</para>
+		<para>Default: shadow:mountpoint = NOT SPECIFIED</para>
+                </listitem>
+                </varlistentry>
+
+		<varlistentry>
                 <term>shadow:snapdir = SNAPDIR
                 </term>
                 <listitem>
-                <para>Path to the directory where snapshots are kept.
-                </para>
+		<para>
+		Path to the directory where the file system of
+		the share keeps its snapshots.
+		If an absolute path is specified, it is used as-is.
+		If a relative path is specified, then it is taken
+		relative to the mount point of the filesystem of
+		the share root. (See <command>shadow:mountpoint</command>.)
+		</para>
+		<para>
+		Note that <command>shadow:snapdirseverywhere</command>
+		depends on this parameter and needs a relative path.
+		Setting an absolute path disables
+		<command>shadow:snapdirseverywhere</command>.
+		</para>
+		<para>
+		Note that the <command>shadow:crossmountpoints</command>
+		option also requires a relative snapdir.
+		Setting an absolute path disables
+		<command>shadow:crossmountpoints</command>.
+		</para>
+		<para>Example: shadow:snapdir = /some/absolute/path</para>
+		<para>Default: shadow:snapdir = .snapshots</para>
                 </listitem>
                 </varlistentry>
 
@@ -101,21 +181,65 @@
                 <term>shadow:basedir = BASEDIR
 		</term>
                 <listitem>
-                <para>Path to the base directory that snapshots are from.
-                </para>
+		<para>
+		The basedir option allows to specify a directory
+		between the share's mount point and the share root,
+		relative to which the file system's snapshots are taken.
+		</para>
+		<para>
+		For example, if
+		<itemizedlist>
+		<listitem><para>
+		<command>basedir = mountpoint/rel_basedir</command>
+		</para></listitem>
+		<listitem><para>
+		<command>share_root = basedir/rel_share_root</command>
+		</para></listitem>
+		<listitem><para>
+		<command>snapshot_path = mountpoint/snapdir</command>
+		</para>
+		<para>
+		or
+		<command>snapshot_path = snapdir</command>
+		if snapdir is absolute
+		</para></listitem>
+		</itemizedlist>
+		then the snapshot of a
+		<command>file = mountpoint/rel_basedir/rel_share_root/rel_file</command>
+		at a time TIME will be found under
+		<command>snapshot_path/FS_GMT_TOKEN(TIME)/rel_share_root/rel_file</command>,
+		where FS_GMT_TOKEN(TIME) is the timestamp string belonging
+		to TIME in the format required by the file system.
+		(See <command>shadow:format</command>.)
+		</para>
+		<para>The default for the basedir is the mount point
+		of the file system of the share root
+		(see <command>shadow:mountpoint</command>).
+		</para>
+		<para>
+		Note that the <command>shadow:snapdirseverywhere</command>
+		and  <command>shadow:crossmountpoints</command>
+		options are incompatible with <command>shadow:basedir</command>
+		and disable the basedir setting.
+		</para>
                 </listitem>
                 </varlistentry>
 
 		<varlistentry>
-                <term>shadow:sort = asc/desc, or not specified for unsorted (default)
+                <term>shadow:sort = asc/desc
                 </term>
                 <listitem>
-                <para>By this parameter one can specify that the shadow
-		copy directories should be sorted before they are sent to the
-		client.  This can be beneficial as unix filesystems are usually
-		not listed alphabetically sorted. If enabled, you typically
-		want to specify descending order.
-                </para>
+		<para>By default, this module sorts the shadow copy data
+		alphabetically before sending it to the client.
+		With this parameter, one can specify the sort order.
+		Possible known values are desc (descending, the default)
+		and asc (ascending). If the file system lists directories
+		alphabetically sorted, one can turn off sorting in this
+		module by specifying any other value.
+		</para>
+		<para>Example: shadow:sort = asc</para>
+		<para>Example: shadow:sort = none</para>
+		<para>Default: shadow:sort = desc</para>
                 </listitem>
                 </varlistentry>
 
@@ -124,9 +248,10 @@
                 </term>
                 <listitem>
                 <para>This is an optional parameter that indicates whether the
-		snapshot names are in UTC/GMT or in local time. By default
-		UTC is expected.
+		snapshot names are in UTC/GMT or in local time. If it is
+		disabled then UTC/GMT is expected.
                 </para>
+		<para>shadow:localtime = no</para>
                 </listitem>
                 </varlistentry>
 
@@ -135,14 +260,28 @@
                 </term>
                 <listitem>
                 <para>This is an optional parameter that specifies the format
-		specification for the naming of snapshots.  The format must
-		be compatible with the conversion specifications recognized
-		by str[fp]time.  The default value is "@GMT-%Y.%m.%d-%H.%M.%S".
+		specification for the naming of snapshots in the file system.
+		The format must be compatible with the conversion
+		specifications recognized by str[fp]time.
                 </para>
+		<para>Default: shadow:format = "@GMT-%Y.%m.%d-%H.%M.%S"</para>
                 </listitem>
                 </varlistentry>
 
 		<varlistentry>
+		<term>shadow:sscanf = yes/no</term>
+		<listitem>
+		<para>
+		This paramter can be used to specify that the time in
+		format string is given as an unsigned long integer (%lu)
+		rather than a time strptime() can parse.
+		The result must be a unix time_t time.
+		</para>
+		<para>Default: shadow:sscanf = no</para>
+		</listitem>
+		</varlistentry>
+
+		<varlistentry>
                 <term>shadow:fixinodes = yes/no
                 </term>
                 <listitem>
@@ -155,23 +294,78 @@
 		this option then the 'restore' button in the shadow copy UI
 		will fail with a sharing violation.
                 </para>
+		<para>Default: shadow:fixinodes = no</para>
                 </listitem>
                 </varlistentry>
+
 		<varlistentry>
 		<term>shadow:snapdirseverywhere = yes/no
 		</term>
 		<listitem>
-		<para>If you enable <command moreinfo="none">
-		shadow:snapdirseverywhere </command> then this module will look
-		out for snapshot directories in the current and all parent
-		directories of the current working directory.
+		<para>
+		If you enable
+		<command moreinfo="none">shadow:snapdirseverywhere </command>
+		then this module will look
+		out for snapshot directories in the current working directory
+		and all parent directories, stopping at the mount point
+		by default.
+		But see <command>shadow:crossmountpoints</command> how to change
+		that behaviour.
+		</para>
+		<para>
 		An example where this is needed are independent filesets in
 		IBM's GPFS, but other filesystems might support snapshotting
 		only particular subtrees of the filesystem as well.
 		</para>
+		<para>
+		Note that <command>shadow:snapdirseverywhere</command>
+		depends on <command>shadow:snapdir</command> and needs it to be
+		a relative path. Setting an absolute snapdir path disables
+		<command>shadow:snapdirseverywhere</command>.
+		</para>
+		<para>
+		Note that this option is incompatible with the
+		<command>shadow:basedir</command> option and removes the
+		<command>shadow:basedir</command> setting by itself.
+		</para>
+		<para>Example: shadow:snapdirseverywhere = yes</para>
+		<para>Default: shadow:snapdirseverywhere = no</para>
 		</listitem>
 		</varlistentry>
 
+		<varlistentry>
+                <term>shadow:crossmountpoints = yes/no
+                </term>
+                <listitem>
+		<para>
+		This option is effective in the case of
+		<command>shadow:snapdirseverywhere = yes</command>.
+		Setting this option makes the module not stop at the
+		first mount point encountered when looking for snapdirs,
+		but lets it search potentially all through the path
+		instead.
+                </para>
+		<para>
+		An example where this is needed are independent filesets in
+		IBM's GPFS, but other filesystems might support snapshotting
+		only particular subtrees of the filesystem as well.
+		</para>
+		<para>
+		Note that <command>shadow:snapdirseverywhere</command>
+		depends on <command>shadow:snapdir</command> and needs it to be
+		a relative path. Setting an absolute snapdir path disables
+		<command>shadow:snapdirseverywhere</command>.
+		</para>
+		<para>
+		Note that this option is incompatible with the
+		<command>shadow:basedir</command> option and removes the
+		<command>shadow:basedir</command> setting by itself.
+		</para>
+		<para>Example: shadow:crossmountpoints = yes</para>
+		<para>Default: shadow:crossmountpoints = no</para>
+                </listitem>
+                </varlistentry>
+
 		</variablelist>
 </refsect1>
 
@@ -209,7 +403,7 @@
 <refsect1>
 	<title>VERSION</title>
 
-	<para>This man page is correct for version 3.2.7 of the Samba suite.
+	<para>This man page is correct for version 4.0 of the Samba suite.
 	</para>
 </refsect1>