Beruflich Dokumente
Kultur Dokumente
Table of contents
Table of contents.......................................................................................................................................... 1
Introduction.................................................................................................................................................. 1
Command line options................................................................................................................................. 2
Shadow copy creation............................................................................................................................. 2
Shadow copy import................................................................................................................................ 3
Shadow copy query................................................................................................................................. 3
Shadow copy deletion............................................................................................................................. 3
Breaking a shadow copy set.................................................................................................................... 4
Exposing a shadow copy locally.............................................................................................................. 4
Exposing a shadow copy remotely.......................................................................................................... 4
Listing writers and their status/metadata.................................................................................................5
Writer restore........................................................................................................................................... 5
Other command-line flags....................................................................................................................... 6
Shadow copy management topics............................................................................................................... 6
How to access shadow copy properties from a CMD script.....................................................................6
How to access non-persistent shadow copies.........................................................................................7
How to manage transportable shadow copies......................................................................................... 8
Writer and component related topics........................................................................................................... 9
Selecting volumes for shadow copy creation........................................................................................... 9
Verification of writer/component inclusion................................................................................................ 9
Writer/component exclusion.................................................................................................................. 10
Component selection during shadow copy creation...............................................................................11
Component selection for restore........................................................................................................... 12
Test scripts for shadow copy management................................................................................................ 12
Shadow_test_server.cmd...................................................................................................................... 12
Shadow_test_xp.cmd............................................................................................................................ 13
Test scripts for backup and restore............................................................................................................ 13
Compatibility notes.................................................................................................................................... 14
What are the limitations of VSHADOW?.................................................................................................... 14
List of files in the VSHADOW project......................................................................................................... 15
Building the sample code........................................................................................................................... 16
Introduction
This tool serves as a sample VSS application that demonstrates various tasks performed by a regular VSS
requestor. VSHADOW.EXE (formerly known as VSNAP.EXE) also offers a simple command-line interface for
VSS management, including shadow copy creation, deletion and query.
The sample code is can be compiled with Visual C++ 2003 and requires the Platform SDK. VSHADOW can
be compiled on a single EXE in two modes, targeting either Windows XP or Windows Server 2003 (but not
both).
Page 1 of 16
Notes
The specified list of volumes should use spacing characters as separators. The volumes can optionally be
terminated with a backspace, so both C: and C:\ are valid volumes. You can also specify mount points (for
example c:\foo) or volume names (like \\?\Volume{edbed95e-7e8d-11d8-9d01-505054503030}\)
When the shadow copy is created with writers, VSHADOW will automatically select all affected writer
components by the specified volume. You can see the list of affected volumes for each writer by using the wm option (listing the writer metadata). A writer can be specifically excluded from the shadow copy process
by using the wx option. Also, you can verify if a writer is included through the -wi option. Please see the
chapter titled Shadow Copy management topics for more details on shadow creation with VSHADOW.
The shadow devices will appear in the system during creation, excepting in the transportable shadow
creation mode (the -t option). In the transportable case, you must have a subsequent import phase on the
same machine or on a different machine. Please see the shadow copy import chapter for more details.
Page 2 of 16
copies.
-wait
-tracing
- Wait for the user interaction before exiting. This will keep alive nonpersistent shadows.
- Verbose output useful for diagnosis.
Notes
The {file.xml} file must be a backup components file previously created with the t option.
Note that when the shadow copy was originally created as non-persistent, the device will appear for a short
time while the VSHADOW i= command is running, and will automatically go away when the program
execution ends. You can access these devices only through an optional script executed through -exec
command.
Notes:
The implementation uses either QuerySnapshots or GetSnapshotProperties APIs to display the properties of
the given set of shadow copies.
Notes:
The da option requires user confirmation.
Page 3 of 16
Non-persistent shadow copies will be automatically deleted when the VSHADOW creation/import process
exits (except if Break was called on the shadow set prior to exit).
- Break the given shadow copy set into standalone read-only volumes.
- Break the shadow copy set into standalone writable volumes
Notes:
Non-persistent shadow copies can be accessed only though the exec scripts. To preserve the device
beyond the program VSHADOW execution you must break the non-persistent shadow in a special script
through the exec command.
Page 4 of 16
-bw to convert this shadow copy into a standalone volume, and you change the security access to the share
object.
Client accessible shadow copies cannot be exposed remotely.
Syntax:
VSHADOW -er={SnapID},UnusedShareName
VSHADOW -er={SnapID}, UnusedShareName,PathFromRootOnShadow
Example:
Lets assume that {8e8c4b6a-03b2-481c-94ac-6eb6c9bcdc1c} is the ID of an existing shadow copy, and that
share_123 is an unused share name. The following command will expose the shadow copy under this share:
VSHADOW -er={8e8c4b6a-03b2-481c-94ac-6eb6c9bcdc1c},share_123
Alternatively, we can expose only a certain sub-tree of the shadow copy. Lets assume that the shadow copy
contains a directory \Folder1. The, you can expose the shadow copy image of the sub-tree under
\Folder1\Folder2 like this:
VSHADOW -er={8e8c4b6a-03b2-481c-94ac-6eb6c9bcdc1c},share_123,Folder1\Folder2
Writer restore
Syntax:
VSHADOW [optional list of flags] -r={file.xml}
VSHADOW [optional list of flags] -rs={file.xml}
Flags:
-wi={writer}
-wx={writer}
-exec={command}
-tracing
Notes
Page 5 of 16
The {file.xml} file must be a backup components file previously created during a shadow copy creation with
either the t or bc options.
A writer can be specifically excluded from the restore process by using the wx option (like in the case of
shadow set creation). Also, you can verify if a writer is included through the -wi option.
The restore process has four main parts:
1) Select the components that are present in the backup components document.
2) Notify the affected writers that a restore is about to begin (the Pre-restore event)
3) Performing the actual restore of the writer files. This must be done through the custom command
specified in the exec option.
4) Notify the affected writers that a restore is about to begin (the Post-restore event)
You can also perform a simulated restore through the -rs option. A simulated restore performs only the first
step above and does not affect writers nor does replace any data. This option might be very useful to
preview the list of components that will be restored by a subsequent restore.
There are various approaches to perform the actual restore. Some examples are given below:
1) The most direct solution would be to manually stop/offline the writer processes through the restore
script, and copy the files to their original location.
2) A more advanced solution for quick restore uses a transportable Import process, performed through
the exec script. In this script you can call another instance of VSNAP that performs the Import.
3) An alternative solution will dismount and mask the original volumes affected by the restore, and
replacing them with a corresponding set of previously-imported volumes.
Note that VSHADOW.EXE implements only minimal restore functionality, and does not implement some
advanced features that are required for a true requestor. Please consult the VSS SDK for more details on
the restore process.
Designing a restore procedure with VSHADOW requires manual inspection the writer restore options
through the VSHADOW wm option. Please see the tests for a sample utilization of the restore options to
backup & restore a SQL database.
The -tracing flag will show a verbose output, including the call execution order. This might be
useful to diagnose the source code.
The -wait flag will stop VSHADOW at the end and ask the user to press ENTER to continue. This
is useful when you create/import a non-persistent shadow copy since the shadow copy will be
deleted right after the program exits. So this flag will allow you to see the created shadow copy.
Page 6 of 16
The shadow copy device: the %VSHADOW_DEVICE_NNN% variable where NNN represents the
index of the source volume in the command-line.
You can use this generated script to perform controlled management on the created shadow copies. For
example, you can expose a created shadow copy in this way:
VSHADOW -p -nw -script=SETVAR1.cmd c:
call SETVAR1.cmd
VSHADOW -el=%VSHADOW_ID_1%,c:\directory1
Page 7 of 16
For security reasons and to keep the implementation simple, the exec will not accepts parameters
to be passed to the custom command. The whole string passed to the exec command is treated as
a single CMD/EXE file. See the sources for more comments on this limitation.
Note that the BackupComplete writer event is sent after the -exec script/command is executed.
The BackupComplete sent to the writers signals that the backup is completed, and the writer can
potentially truncate logs at this point. Therefore it is important to verify that the shadow/backup
actually completed, and if the backup failed then you can abort the creation process by returning a
non-zero exit code in the executed script/command (see the EXIT command for more details). If the
custom command returns with a non-zero exit code, then the shadow copy creation is aborted and
BackupComplete wont be called.
Page 8 of 16
VSHADOW el=%VSHADOW_ID_1%,c:\mount_point
6) Finally, break the shadow set to make the volumes writable.
VSHADOW bw=%VSHADOW_SET_ID%
One final note: non-persistent shadow copies can still be imported, but they will go away as soon as the
VSHADOW -i" process exits. To use these devices you must execute a script during import (through the
exec command) that would eventually expose the devices locally and then break the set.
wi=WriterName:\LogicalPath\ComponentName
{creation
Additionally, you can verify if all components from a certain writer will be included:
VSHADOW wi=WriterName
VSHADOW wi="Writer name"
Page 9 of 16
You can specify a set of writers/components by specifying the -wi flag several times in the same command
line. For example:
VSHADOW -wi="Registry Writer:\Registry" -wi=COM+ REGDB Writer
The component string as accepted by VSHADOW can be viewed using the VSHADOW wm" command.
Here is an example:
C:\> VSHADOW -wm
VSHADOW.EXE 2.0 - Volume Shadow Copy sample client
Copyright (C) 2004 Microsoft Corporation. All rights reserved.
(Option: List writer metadata)
(Gathering writer metadata...)
Initialize writer metadata ...
Listing writer metadata ...
* WRITER 'MSDEWriter'
- WriterId
= {01b5efaa-1b5f0ba-6f73c-6f7306f7906f7286f73c6f73c1bd483c6f73c6f73c}
- InstanceId = {0006f74c-6f730-6f73c-6f7286f74c-6f73c0100001050e8a4d}
- Excluded files:
- Component "MSDEWriter:\AOLTEAN-DEV\SRMSERVICES\master"
- Name: 'master'
- Logical Path: 'AOLTEAN-DEV\SRMSERVICES'
- Full Path: '\AOLTEAN-DEV\SRMSERVICES\master'
- Caption: ''
- Type: VSS_CT_DATABASE [1]
- Is Selectable: 'TRUE'
- Is top level: 'TRUE'
- Notify on backup complete: 'FALSE'
- Affected paths by this component:
- C:\Program Files\Microsoft SQL Server\MSSQL$SRMSERVICES\Data
- Affected volumes by this component:
- \\?\Volume{4bcddd9a-9e9e-11d6-b7f4-806e6f6e6963}\ [C:\]
C:\> VSHADOW wi="MSDEWriter:\AOLTEAN-DEV\SRMSERVICES\master" c:
Writer/component exclusion
Additionally, it is possible to explicitly exclude a certain list of writers\components during snapshot creation or
restore. For example you would like to avoid certain writers that fail during snapshot creation. Or, you might
want to restore only certain components.
This option has a similar syntax with the -wi option. To exclude a certain writer, use the wx option:
VSHADOW wx=WriterName
VSHADOW wx="Writer name"
VSHADOW wx={WriterID}
Page 10 of 16
Also, you can exclude a certain component from a writer. You can use the same syntax as above except that
you append a colon character to the writer name, followed by the logical path and the component name. A
backslash must be present between the logical path and the component name.
VSHADOW
options}
VSHADOW
VSHADOW
VSHADOW
wx=WriterName:\LogicalPath\ComponentName
{creation
You can specify a set of writers/components by specifying the -wx flag several times in the same command
line. For example:
VSHADOW -wx="Registry Writer:\Registry" -wx=COM+ REGDB Writer
Page 11 of 16
Then we discover all excluded components. These are all components that have at least one
directly excluded descendent.
Then we discover if the writer needs to be excluded. The writer will be excluded if:
o Either all its selectable components are excluded
o Or the writer contains at least one excluded top-level non-selectable component
We establish now the list of explicitly included components:
o First, we isolate the subset of components that are candidate for explicit inclusion
Either selectable non-excluded components
Or non-selectable top-level non-excluded components
o From the list above we retain the roots, i.e. components that
Are candidate for explicit exclusion
Have no ancestors that are candidate for explicit exclusion
Finally, we select all the explicitly included components using AddComponent.
Page 12 of 16
Shadow_test_server.cmd
This test can be used to exercise VSHADOW on Windows Server 2003.
Usage:
Shadow_test_server.cmd [test-type] [drive letter] [expose as letter]
Parameters:
- test-type: takes value as "1" or "2".
"1" refers to tests executed using software provider or volsnap.
"2" refers to hardware-provider specific tests.
- drive letter: Value for this parameter is either target volume name or drive configured using hardware
provider. If tests pertaining to volsnap needs to be executed, then this drive letter should be an NTFS
volume which is not system volume. If hardware-provider specific tests need to be executed, then this drive
letter should be drive configured using hardware provider.
- expose as letter: Provide a drive letter not is not in use. It will be used to expose shadow copy locally.
Notes:
The test script assumes that the system drive is C: and is formatted with NTFS.
Examples:
Shadow_test_server 1 m: x:
Shadow_test_server 2 f: x:
Shadow_test_xp.cmd
This test can be used to exercise main VSHADOW functionality on Windows XP.
Usage:
SHADOW_TEST_XP.CMD [drive_letter]
Parameters:
- drive letter: Value for this parameter is either target volume name. This drive letter should be an volume
which is not system volume.
Notes:
The test script assumes that the system drive is C: and is formatted with NTFS.
Examples:
Shadow_test_xp f:
Page 13 of 16
These tests exercise a simple backup-restore scenario of a SQL database with vshadow.exe. The test uses
VSHADOW to backup a temporary copy of the pubs database, performs certain modifications to the
database, restore the previous version and verifies that the restore was correct.
Instructions for running the tests are presented below:
1) Install SQL Server or MSDE
2) Copy the content of the tests\backup_restore folder to a new directory on the test machine. Ensure that
this directory path contains no spaces.
3) Edit the "setvar.cmd" file to configure the test parameters (the SQL/MSDE instance name, etc)
4) Copy VSHADOW.EXE in this new test directory
5) Run "run_test.cmd"
6) If you do not see TEST FAILED in the output, the test passed.
The cleanup script is cleanup_test.cmd. This basically deletes all temporary files and directories
(in the form _XXXXX) that were created during the test.
Compatibility notes
The VSS API is dependent on the operating system type. Your requestor must be compiled either for XP or
Windows server 2003. You cannot have the same VSS requestor binary running on both platforms since the
VSSAPI.DLL in Windows XP is not binary compatible with VSSAPI.DLL in Windows Server 2003 or future
Windows versions.
Still, you can have the same source code for your VSS requestor on both XP and Windows Server 2003 like
VSHADOW does. First, you must set the project to use different VSS headers/libs between XP and Server
build configurations. In addition, we defined two macros that allow using the same source code for both XP
and WS03 targets:
- VSS_SERVER macro should be defined only for Windows Server 2003 projects
- VSS_XP macro should be defined only for Windows XP projects
There are some differences between features offered by VSS in XP and Server. Some of the differences are
mentioned below:
1) On XP, the only supported shadow copy type is non-persistent with writers. There is no way to
create persistent shadow copies or shadow copies without writers.
2) On XP we do not support VSS HW providers.
3) On XP the shadow copy expose API is not implemented.
4) There are certain additions in the VSS Server API, for example new writer restore methods, writer
dependencies, etc.
5) On XP there is no VDS API.
Finally, note that the transportable shadow copy is a feature of Windows Server 2003 Enterprise and
Datacenter editions. Transportable shadow copies are not supported in other SKUs, like Windows Server
2003 Standard or Windows XP.
Page 14 of 16
VSHADOW does not allow selecting components through the command-line. You must instead
specify a set of volumes such that the set of desired components will be automatically selected. Still,
you can verify whether a certain set of components is selected using the -wi option.
VSHADOW does not contain any file-copying code required by a true backup application.
VSHADOW does not have any VSS backup and restore functionality. Please see the BETEST
sample code for a full implementation of a VSS backup/restore application.
The component consistency verification algorithm in VSHADOW has two limitations. Please see the
next chapter (Component selection in VSHADOW) for more details.
o The algorithm will not follow component dependencies.
o The algorithm will not follow mount point chains in recursive file descriptor specifications.
VSHADOW assumes that all file descriptors contain data on a single volume.
A real requestor will have to add additional code to deal with the two scenarios described above. To test your
requestor, make sure that you respect all the component selection rules outlined in the latest VSS SDK.
Make sure that your requestor works with the VSS test writer, which should exercise these scenarios. Also,
you need to test your requestor with all known writers on the targeted SKUs.
Finally, we should note that VSHADOW only implements minimal restore functionality, assuming that the
files are always restored in the same location as during the shadow creation. VSHADOW does not
implement some advanced features that are required for a true requestor, like complex restore methods,
stopping/starting writer services, rebooting the machine, sub-component selection, alternate targets, etc.
.\INC\{xp|ws03}
File name
macros.h
create.cpp
delete.cpp
break.cpp
query.cpp
stdafx.cpp
stdafx.h
tracing.cpp
tracing.h
util.h
shadow.cpp
shadow.h
vssclient.cpp
vssclient.h
Writer.h
Select.cpp
writer.cpp
src.vcproj
strsafe.h
vds.h
.\BIN\{debug|release}-
Page 15 of 16
Vsbackup.h
vss.h
vswriter.h
VShadow.exe
Description
Useful macros
VSS shadow copy creation code
VSS shadow copy deletion code
VSS shadow copy break code
VSS shadow copy query code
Precompiled header (general declarations)
Very simple tracing/logging class
Utility routines (string conversion, volume APIs, etc)
VSHADOW command-line specific code (CLI parsing, usage
routine, etc)
Declaration/definition of the VSS API wrapper class.
VSS writer metadata wrappers (writer, component, file
descriptor, etc)
Component selection code.
Implementation of VSS writer metadata wrappers
Visual Studio project file
External dependency: Defines safe printf-style APIs, free of
buffer overruns (see MSDN for more details)
External dependency: VDS header (also included in the VDS
SDK)
External dependency: VSS headers (also included in the VSS
SDK)
Compiled binaries and symbols.
{xp|ws03}
.\LIB\{xp|ws03}
VShadow.pdb
vssapi.lib
vss_uuid.lib
.\tests\shadow_creation
.\tests\backup_restore
.\
readme.doc
VShadow.sln
Page 16 of 16