[SCM] Samba Shared Repository - branch master updated
Andrew Bartlett
abartlet at samba.org
Fri Dec 6 14:27:04 MST 2013
The branch, master has been updated
via f6ac6f2 docs: update the manpage of vfs_shadow_copy2
via 6685e65 s3:modules:shadow_copy2: remove redundant documentation comment block
via bffaf17 s3:modules:shadow_copy2: improve headline comment
via b5b5674 s3:module:shadow_copy2: add my (C)
from 5173322 s4:torture:smb2: add new durable-v2-open.reopen1a test
http://gitweb.samba.org/?p=samba.git;a=shortlog;h=master
- Log -----------------------------------------------------------------
commit f6ac6f20540f81257e1f180454b6a2c1239e85fa
Author: Michael Adam <obnox at samba.org>
Date: Wed Dec 4 10:27:24 2013 +0100
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 at sernet.de>
Signed-off-by: Michael Adam <obnox at samba.org>
Reviewed-by: Andrew Bartlett <abartlet at samba.org>
Autobuild-User(master): Andrew Bartlett <abartlet at samba.org>
Autobuild-Date(master): Fri Dec 6 22:26:31 CET 2013 on sn-devel-104
commit 6685e6512e03d9420439a730a40fcca3411a48db
Author: Michael Adam <obnox at samba.org>
Date: Wed Dec 4 15:55:19 2013 +0100
s3:modules:shadow_copy2: remove redundant documentation comment block
and refer to the manual page instead
Signed-off-by: Michael Adam <obnox at samba.org>
Reviewed-by: Volker Lendecke <vl at samba.org>
Reviewed-by: Andrew Bartlett <abartlet at samba.org>
commit bffaf17d482cb1ad88698ea1a00aa7e4ddb0c0e7
Author: Michael Adam <obnox at samba.org>
Date: Wed Dec 4 15:50:26 2013 +0100
s3:modules:shadow_copy2: improve headline comment
Signed-off-by: Michael Adam <obnox at samba.org>
Reviewed-by: Volker Lendecke <vl at samba.org>
Reviewed-by: Andrew Bartlett <abartlet at samba.org>
commit b5b5674287c935bf923cf570cf218ffb0ae7ce78
Author: Michael Adam <obnox at samba.org>
Date: Wed Dec 4 13:40:14 2013 +0100
s3:module:shadow_copy2: add my (C)
Signed-off-by: Michael Adam <obnox at samba.org>
Reviewed-by: Volker Lendecke <vl at samba.org>
Reviewed-by: Andrew Bartlett <abartlet at samba.org>
-----------------------------------------------------------------------
Summary of changes:
docs-xml/manpages/vfs_shadow_copy2.8.xml | 290 +++++++++++++++++++++++++-----
source3/modules/vfs_shadow_copy2.c | 84 +--------
2 files changed, 248 insertions(+), 126 deletions(-)
Changeset truncated at 500 lines:
diff --git a/docs-xml/manpages/vfs_shadow_copy2.8.xml b/docs-xml/manpages/vfs_shadow_copy2.8.xml
index 1615e8a..823c1f8 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 + at 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>
diff --git a/source3/modules/vfs_shadow_copy2.c b/source3/modules/vfs_shadow_copy2.c
index ebc50e9..8243f63 100644
--- a/source3/modules/vfs_shadow_copy2.c
+++ b/source3/modules/vfs_shadow_copy2.c
@@ -1,10 +1,11 @@
/*
- * Third attempt at a shadow copy module
+ * shadow_copy2: a shadow copy module (second implementation)
*
* Copyright (C) Andrew Tridgell 2007 (portions taken from shadow_copy2)
* Copyright (C) Ed Plese 2009
* Copyright (C) Volker Lendecke 2011
* Copyright (C) Christian Ambach 2011
+ * Copyright (C) Michael Adam 2013
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
@@ -22,83 +23,10 @@
*/
/*
-
- This is a 3rd implemetation of a shadow copy module for exposing
- snapshots to windows clients as shadow copies. This version has the
- following features:
-
- 1) 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]
-
- 2) 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
-
- 3) shadow copy results can be sorted before being sent to the
- client. This is beneficial for filesystems that don't read
- directories alphabetically (the default unix).
-
- 4) vanity naming for snapshots. Snapshots can be named in any
- format compatible with str[fp]time conversions.
-
- 5) time stamps in snapshot names can be represented in localtime
- rather than UTC.
-
- Module options:
-
- shadow:snapdir = <directory where snapshots are kept>
-
- This is the directory containing the @GMT-* snapshot directories. If it is an absolute
- path it is used as-is. If it is a relative path, then it is taken relative to the mount
- point of the filesystem that the root of this share is on
-
- shadow:basedir = <base directory that snapshots are from>
-
- This is an optional parameter that specifies the directory that
- the snapshots are relative to. It defaults to the filesystem
- mount point
-
- shadow:fixinodes = yes/no
-
- If you enable shadow:fixinodes then this module will modify the
- apparent inode number of files in the snapshot directories using
- a hash of the files path. This is needed for snapshot systems
- where the snapshots have the same device:inode number as the
- original files (such as happens with GPFS snapshots). If you
- don't set this option then the 'restore' button in the shadow
- copy UI will fail with a sharing violation.
-
- shadow:sort = asc/desc, or not specified for unsorted (default)
-
- This is an optional parameter that specifies that the shadow
- copy directories should be sorted before sending them 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.
-
- shadow:format = <format specification for snapshot names>
-
- 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".
-
- shadow:sscanf = yes/no (default is no)
-
- The time is the unsigned long integer (%lu) in the format string
- rather than a time strptime() can parse. The result must be a unix time_t
- time.
-
- shadow:localtime = yes/no (default is no)
-
- This is an optional parameter that indicates whether the
- snapshot names are in UTC/GMT or the local time.
-
-
- The following command would generate a correctly formatted directory name
- for use with the default parameters:
- date -u + at GMT-%Y.%m.%d-%H.%M.%S
+ * This is a second implemetation of a shadow copy module for exposing
+ * file system snapshots to windows clients as shadow copies.
+ *
+ * See the manual page for documentation.
*/
#include "includes.h"
--
Samba Shared Repository
More information about the samba-cvs
mailing list