[PATCHSET] Update and fix documentation of shadow_copy2
Michael Adam
obnox at samba.org
Fri Dec 6 00:46:29 MST 2013
Hi,
attached find a patchset that updates and extends the manual
page for shadow_copy2, documenting the various more or less
recent changes.
Also, the shadow_copy2.c code file is pruned of redundant
and partly outdated comments and equipped with a hint
to the manual page.
For convenience, also find attached the compiled
manual page. The patches can be found in my
master-shadow_copy2 branch in
git://git.samba.org/obnox/samba/samba-obnox.git
This was my "hygiene item" I needed to fix before
bringing the recent fixes to shadow_copy2 to the 4.X
releases...
Comment/review/push appreciated.
Cheers - Michael
-------------- next part --------------
From 8d1ea994795fd0bf6c2ffcd846138f379a08e2b1 Mon Sep 17 00:00:00 2001
From: Michael Adam <obnox at samba.org>
Date: Wed, 4 Dec 2013 13:40:14 +0100
Subject: [PATCH 1/4] s3:module:shadow_copy2: add my (C)
Signed-off-by: Michael Adam <obnox at samba.org>
---
source3/modules/vfs_shadow_copy2.c | 1 +
1 file changed, 1 insertion(+)
diff --git a/source3/modules/vfs_shadow_copy2.c b/source3/modules/vfs_shadow_copy2.c
index ebc50e9..1018bcc 100644
--- a/source3/modules/vfs_shadow_copy2.c
+++ b/source3/modules/vfs_shadow_copy2.c
@@ -5,6 +5,7 @@
* 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
--
1.7.9.5
From 96f3cd4cc56efc8d8a534601be73914453606166 Mon Sep 17 00:00:00 2001
From: Michael Adam <obnox at samba.org>
Date: Wed, 4 Dec 2013 15:50:26 +0100
Subject: [PATCH 2/4] s3:modules:shadow_copy2: improve headline comment
Signed-off-by: Michael Adam <obnox at samba.org>
---
source3/modules/vfs_shadow_copy2.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/source3/modules/vfs_shadow_copy2.c b/source3/modules/vfs_shadow_copy2.c
index 1018bcc..41a2a0e 100644
--- a/source3/modules/vfs_shadow_copy2.c
+++ b/source3/modules/vfs_shadow_copy2.c
@@ -1,5 +1,5 @@
/*
- * 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
--
1.7.9.5
From 9f9d4c58435306ca0149567e7c4bc870edfb2065 Mon Sep 17 00:00:00 2001
From: Michael Adam <obnox at samba.org>
Date: Wed, 4 Dec 2013 15:55:19 +0100
Subject: [PATCH 3/4] 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>
---
source3/modules/vfs_shadow_copy2.c | 81 ++----------------------------------
1 file changed, 4 insertions(+), 77 deletions(-)
diff --git a/source3/modules/vfs_shadow_copy2.c b/source3/modules/vfs_shadow_copy2.c
index 41a2a0e..8243f63 100644
--- a/source3/modules/vfs_shadow_copy2.c
+++ b/source3/modules/vfs_shadow_copy2.c
@@ -23,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"
--
1.7.9.5
From 63187765cb51998b173b3637da5c258576e8619c Mon Sep 17 00:00:00 2001
From: Michael Adam <obnox at samba.org>
Date: Wed, 4 Dec 2013 10:27:24 +0100
Subject: [PATCH 4/4] docs: update the manpage of vfs_shadow_copy2
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
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>
---
docs-xml/manpages/vfs_shadow_copy2.8.xml | 277 ++++++++++++++++++++++++------
1 file changed, 229 insertions(+), 48 deletions(-)
diff --git a/docs-xml/manpages/vfs_shadow_copy2.8.xml b/docs-xml/manpages/vfs_shadow_copy2.8.xml
index 1615e8a..0892634 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,10 +260,11 @@
</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>
@@ -155,23 +281,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 +390,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>
--
1.7.9.5
-------------- next part --------------
'\" t
.\" Title: vfs_shadow_copy2
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\" Date: 12/06/2013
.\" Manual: System Administration tools
.\" Source: Samba 4.1
.\" Language: English
.\"
.TH "VFS_SHADOW_COPY2" "8" "12/06/2013" "Samba 4\&.1" "System Administration tools"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
vfs_shadow_copy2 \- Expose snapshots to Windows clients as shadow copies\&.
.SH "SYNOPSIS"
.HP \w'\ 'u
vfs objects = shadow_copy2
.SH "DESCRIPTION"
.PP
This VFS module is part of the
\fBsamba\fR(7)
suite\&.
.PP
The
vfs_shadow_copy2
VFS module offers a functionality similar to Microsoft Shadow Copy services\&. When set up properly, this module allows Microsoft Shadow Copy clients to browse through file system snapshots as "shadow copies" on Samba shares\&.
.PP
This is a second implementation of a shadow copy module which has the following additional features (compared to the original
\fBshadow_copy\fR(8)
module):
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
There is no need any more to populate your share\*(Aqs 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]\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
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\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
Vanity naming for snapshots: snapshots can be named in any format compatible with with str[fp]time conversions\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
Timestamps can be represented in localtime rather than UTC\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 5." 4.2
.\}
The inode number of the files can optionally be altered to be different from the original\&. This fixes the \*(Aqrestore\*(Aq 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\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 6." 4.2
.\}
Shadow copy results are by default sorted before being sent to the client\&. This is beneficial for filesystems that don\*(Aqt 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\&.
.RE
.sp
.RE
.PP
This module is stackable\&.
.SH "CONFIGURATION"
.PP
vfs_shadow_copy2
relies on a filesystem snapshot implementation\&. Many common filesystems have native support for this\&.
.PP
Filesystem snapshots must be available under specially named directories in order to be recognized by
vfs_shadow_copy2\&. These snapshot directory is typically a direct subdirectory of the share root\*(Aqs mountpoint but there are other modes that can be configured with the parameters described in detail below\&.
.PP
The snapshot at a given point in time is expected in a subdirectory of the snapshot directory where the snapshot\*(Aqs directory is expected to be a formatted version of the snapshot time\&. The default format which can be changed with the
shadow:format
option is @GMT\-YYYY\&.MM\&.DD\-hh\&.mm\&.ss, where:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
YYYY
is the 4 digit year
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
MM
is the 2 digit month
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
DD
is the 2 digit day
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
hh
is the 2 digit hour
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
mm
is the 2 digit minute
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
ss
is the 2 digit second\&.
.sp
.RE
.PP
The
vfs_shadow_copy2
snapshot naming convention can be produced with the following
\fBdate\fR(1)
command:
.sp
.if n \{\
.RS 4
.\}
.nf
TZ=GMT date + at GMT\-%Y\&.%m\&.%d\-%H\&.%M\&.%S
.fi
.if n \{\
.RE
.\}
.SH "OPTIONS"
.PP
shadow:mountpoint = MOUNTPOINT
.RS 4
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\&.
.sp
Example: shadow:mountpoint = /path/to/filesystem
.sp
Default: shadow:mountpoint = NOT SPECIFIED
.RE
.PP
shadow:snapdir = SNAPDIR
.RS 4
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
shadow:mountpoint\&.)
.sp
Note that
shadow:snapdirseverywhere
depends on this parameter and needs a relative path\&. Setting an absolute path disables
shadow:snapdirseverywhere\&.
.sp
Note that the
shadow:crossmountpoints
option also requires a relative snapdir\&. Setting an absolute path disables
shadow:crossmountpoints\&.
.sp
Example: shadow:snapdir = /some/absolute/path
.sp
Default: shadow:snapdir = \&.snapshots
.RE
.PP
shadow:basedir = BASEDIR
.RS 4
The basedir option allows to specify a directory between the share\*(Aqs mount point and the share root, relative to which the file system\*(Aqs snapshots are taken\&.
.sp
For example, if
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
basedir = mountpoint/rel_basedir
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
share_root = basedir/rel_share_root
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
snapshot_path = mountpoint/snapdir
.sp
or
snapshot_path = snapdir
if snapdir is absolute
.sp
.RE
then the snapshot of a
file = mountpoint/rel_basedir/rel_share_root/rel_file
at a time TIME will be found under
snapshot_path/FS_GMT_TOKEN(TIME)/rel_share_root/rel_file, where FS_GMT_TOKEN(TIME) is the timestamp string belonging to TIME in the format required by the file system\&. (See
shadow:format\&.)
.sp
The default for the basedir is the mount point of the file system of the share root (see
shadow:mountpoint)\&.
.sp
Note that the
shadow:snapdirseverywhere
and
shadow:crossmountpoints
options are incompatible with
shadow:basedir
and disable the basedir setting\&.
.RE
.PP
shadow:sort = asc/desc
.RS 4
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\&.
.sp
Example: shadow:sort = asc
.sp
Example: shadow:sort = none
.sp
Default: shadow:sort = desc
.RE
.PP
shadow:localtime = yes/no
.RS 4
This is an optional parameter that indicates whether the snapshot names are in UTC/GMT or in local time\&. If it is disabled then UTC/GMT is expected\&.
.sp
shadow:localtime = no
.RE
.PP
shadow:format = format specification for snapshot names
.RS 4
This is an optional parameter that specifies the format specification for the naming of snapshots in the file system\&. The format must be compatible with the conversion specifications recognized by str[fp]time\&.
.sp
Default: shadow:format = "@GMT\-%Y\&.%m\&.%d\-%H\&.%M\&.%S"
.RE
.PP
shadow:fixinodes = yes/no
.RS 4
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\*(Aqt set this option then the \*(Aqrestore\*(Aq button in the shadow copy UI will fail with a sharing violation\&.
.sp
Default: shadow:fixinodes = no
.RE
.PP
shadow:snapdirseverywhere = yes/no
.RS 4
If you enable
shadow:snapdirseverywhere
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
shadow:crossmountpoints
how to change that behaviour\&.
.sp
An example where this is needed are independent filesets in IBM\*(Aqs GPFS, but other filesystems might support snapshotting only particular subtrees of the filesystem as well\&.
.sp
Note that
shadow:snapdirseverywhere
depends on
shadow:snapdir
and needs it to be a relative path\&. Setting an absolute snapdir path disables
shadow:snapdirseverywhere\&.
.sp
Note that this option is incompatible with the
shadow:basedir
option and removes the
shadow:basedir
setting by itself\&.
.sp
Example: shadow:snapdirseverywhere = yes
.sp
Default: shadow:snapdirseverywhere = no
.RE
.PP
shadow:crossmountpoints = yes/no
.RS 4
This option is effective in the case of
shadow:snapdirseverywhere = yes\&. 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\&.
.sp
An example where this is needed are independent filesets in IBM\*(Aqs GPFS, but other filesystems might support snapshotting only particular subtrees of the filesystem as well\&.
.sp
Note that
shadow:snapdirseverywhere
depends on
shadow:snapdir
and needs it to be a relative path\&. Setting an absolute snapdir path disables
shadow:snapdirseverywhere\&.
.sp
Note that this option is incompatible with the
shadow:basedir
option and removes the
shadow:basedir
setting by itself\&.
.sp
Example: shadow:crossmountpoints = yes
.sp
Default: shadow:crossmountpoints = no
.RE
.SH "EXAMPLES"
.PP
Add shadow copy support to user home directories:
.sp
.if n \{\
.RS 4
.\}
.nf
\fI[homes]\fR
\m[blue]\fBvfs objects = shadow_copy2\fR\m[]
\m[blue]\fBshadow:snapdir = /data/snapshots\fR\m[]
\m[blue]\fBshadow:basedir = /data/home\fR\m[]
\m[blue]\fBshadow:sort = desc\fR\m[]
.fi
.if n \{\
.RE
.\}
.SH "CAVEATS"
.PP
This is not a backup, archival, or version control solution\&.
.PP
With Samba or Windows servers,
vfs_shadow_copy2
is designed to be an end\-user tool only\&. It does not replace or enhance your backup and archival solutions and should in no way be considered as such\&. Additionally, if you need version control, implement a version control system\&.
.SH "VERSION"
.PP
This man page is correct for version 4\&.0 of the Samba suite\&.
.SH "AUTHOR"
.PP
The original Samba software and related utilities were created by Andrew Tridgell\&. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed\&.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 215 bytes
Desc: Digital signature
URL: <http://lists.samba.org/pipermail/samba-technical/attachments/20131206/bcef454a/attachment.pgp>
More information about the samba-technical
mailing list