The VSHADOW sample client

Copyright 2004, Microsoft Corporation.

The VSHADOW sample client

-

Document version: 1.4

Target OS versions: Windows XP, Windows Server 2003
Modification date: 12/8/2004 10:53:00 PM

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

The VSHADOW sample client

Copyright 2004, Microsoft Corporation.

Command line options

The VSHADOW tool can be used for snapshot creation, deletion, query and other management operations
like break or expose. If any of these commands fail, VSHADOW will return the appropriate exit code. You
can detect this exit code through the ERRORLEVEL environment variable.

Shadow copy creation

Syntax:
VSHADOW [optional list of flags] {list of volumes}
Flags:
-p
-nw
-ad
-ap
-scsf
-wi={writer}
-wx={writer}
-t={file.xml}
-bc={file.xml}
-script={file.cmd}
-exec={command}
-wait
-tracing

- Creates persistent shadow copies

- Creates shadow copies without involving writers
- Creates Differential Hardware shadow copies
- Creates Plex Hardware shadow copies
- Creates Shadow Copies for Shared Folders (Client accessible)
- Verifies that a certain writer/component is included
- Excludes a certain writer/component from the shadow copy
- Creates a transportable shadow copy and saves the Backup Components
document into the given file. This file can be used in a subsequent Import
and/or restore.
- Creates a non-transportable shadow copy and saves the Backup
Components document into the given file. This file can be used in a
subsequent restore.
- Generates a CMD file containing environment variables related to created
shadow copies (the shadow copy IDs, the shadow copy set ID, etc)
- Executes a shell command between the shadow set creation and
VSHADOW program exit. Useful for non-persistent shadow copies.
- Wait for the user interaction before exiting. This will keep alive nonpersistent shadows.
- Verbose output useful for diagnosis.

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

The VSHADOW sample client

Copyright 2004, Microsoft Corporation.

Shadow copy import

Syntax:
VSHADOW [optional list of flags] -i={file.xml}
Flags:
-exec={command}

- Executes a shell command between the shadow set creation and

VSHADOW program exit. Useful for non-persistent imported shadow

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.

Shadow copy query

Syntax:
VSHADOW { -q | -qx={SnapSetID} }
Supported flags:
-q
-qx={SnapSetID}
-s={SnapID}

- List all shadow copies in the system

- List all shadow copies in this set
- List the snapshot with the given ID

Notes:
The implementation uses either QuerySnapshots or GetSnapshotProperties APIs to display the properties of
the given set of shadow copies.

Shadow copy deletion

Syntax:
VSHADOW { -da | -dx={SnapSetID} | -ds={SnapSetID} }
Supported flags:
-da
-dx={SnapSetID}
-ds={SnapID}

- Deletes all shadow copies in the system

- Deletes all shadow copies in ths set
- Deletes this shadow copy

Notes:
The da option requires user confirmation.

Page 3 of 16

The VSHADOW sample client

Copyright 2004, Microsoft Corporation.

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).

Breaking a shadow copy set

This command is useful to convert the shadow volumes into standalone read-only/read-write volumes. Note
that after this operation the shadow set is gone from VSS point of view and cannot be used for further
management operations like query, expose or delete.
Syntax:
VSHADOW { -b={SnapSetID} | -bw={SnapSetID} }
Supported flags:
-b={SnapSetID}
-bw={SnapSetID}

- 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.

Exposing a shadow copy locally

This command is used to assign a drive letter or a mount point to a persistent shadow copy. Note that the
volume will be still read-only unless you use a subsequent VSHADOW -bw to convert this shadow copy into
a standalone volume.
Non-persistent shadow copies or client accessible shadow copies cannot be exposed locally.
Syntax:
VSHADOW -el={SnapID},LocalEmptyDirectory
VSHADOW -el={SnapID},UnusedDriveLetter
Example:
Lets assume that {8e8c4b6a-03b2-481c-94ac-6eb6c9bcdc1c} is the ID of an existing persistent shadow
copy, and that X: is an unused drive letter. The following command will expose the shadow copy under X:
VSHADOW -el={8e8c4b6a-03b2-481c-94ac-6eb6c9bcdc1c},x:
Alternatively, the following commands can be used to expose the persistent shadow copy under the mount
point c:\ShadowCopies\Jun23:
MKDIR c:\ShadowCopies\Jun23
VSHADOW -el={8e8c4b6a-03b2-481c-94ac-6eb6c9bcdc1c}, c:\ShadowCopies\Jun23

Exposing a shadow copy remotely

This command is used to assign a read-only share name to the root directory (or a subdirectory) from the
shadow copy. Note that the share contents will remain read-only unless you use a subsequent VSHADOW

Page 4 of 16

The VSHADOW sample client

Copyright 2004, Microsoft Corporation.

-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

Listing writers and their status/metadata

These commands are useful to detect potential failed writers, and to enumerate their components.
Syntax:
VSHADOW -ws
VSHADOW -wm
VSHADOW -wm2
Notes:
The -ws command is the equivalent of VSSADMIN LIST WRITERS. The -wm command will list a summary
of the writer metadata (including the affected volumes). The -wm2 command will list the full writer metadata.
You can use this information to determine what volumes to include in the snapshot set.
Note that as long as the writer is in a STABLE state or WAITING_FOR_COMPLETION, the writer can be
considered in a stable state, ready for the next backup.

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

- Verifies that a certain writer/component is included in restore

- Excludes a certain writer/component from the restore
- Executes a file restore command between the Pre-restore and Postrestore events that were sent to the writers.
- Verbose output useful for diagnosis.

The VSHADOW sample client

Copyright 2004, Microsoft Corporation.

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.

Other command-line flags

-

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.

Shadow copy management topics

How to access shadow copy properties from a CMD script
If you use the -script option during shadow creation, VSHADOW can optionally create a CMD script
containing environment variables representing various useful properties of the created shadow copy/set:
- The shadow set ID: the %VSHADOW_SET_ID% environment variable
- The shadow copy ID: the %VSHADOW_ID_NNN% variable where NNN represents the index of the
source volume in the command-line)

Page 6 of 16

The VSHADOW sample client

-

Copyright 2004, Microsoft Corporation.

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

How to access non-persistent shadow copies

Any non-persistent shadow copies will be automatically deleted when the program that creates them
(VSHADOW.EXE) exits. To access the contents of these shadow copies, VSHADOW offers the ability to
execute a script after the shadow creation but before program exit. To run a script called enum.cmd you
must use the -exec command-line option:
VSHADOW -nw -exec=enum.cmd C:
In the executed script you can also run the generated SETVAR script in this custom command. This allows
the script to access the shadow contents directly. Remember that the shadow device can be retrieved from
the VSHADOW_DEVICE_NNN environment variable. Here is an example:
--- enum.cmd --call SETVAR1.cmd
for /R %VSHADOW_DEVICE_1%\ %%i in (*.*) do @echo %%i
---------------------shadow -nw -exec=c:\enum.cmd -script=setvar1.cmd c:
Note that shadow copies have a special volume device syntax that is not compatible with certain shell
commands - something like \\?\GLOBALROOT\Device\HarddiskVolumeShadowCopyXXX
or \\?\GLOBALROOT\Device\HarddiskVolumeXXX. Still, many Win32 applications or shell commands can
operate on this device. Some examples:
1) Copying a file from a shadow copy:
dir > c:\somefile.txt
VSHADOW -p -nw -script=SETVAR1.cmd c:
call SETVAR1.cmd
copy %VSHADOW_DEVICE_1%\somefile.txt c:\somefile_bak.txt
2) Enumerating all files on a shadow copy device (from a batch file):
dir > c:\somefile.txt
VSHADOW -p -nw -script=SETVAR1.cmd c:
call SETVAR1.cmd
for /R %VSHADOW_DEVICE_1%\ %%i in (*) do @echo %%i
Remember that in a batch file you must use the %%i syntax for FOR variables. In a CMD window, use the
%i syntax instead.
Implementation notes:

Page 7 of 16

The VSHADOW sample client

Copyright 2004, Microsoft Corporation.

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.

How to manage transportable shadow copies

First, you need two separate machines running Windows Server 2003 Enterprise or Datacenter edition. Both
machines must be connected (through a SAN configuration) to a storage array that supports VSS hardware
shadow copies. Then, on each machine, a VSS hardware provider must be installed. Some VSS HW
providers require a special a manual setup process such that transportable shadow copies can be created
on the first machine and imported on the second machine. The VSS SDK provides a software-simulated
hardware provider that can be used for simulating hardware shadow copies. For more information on VSS
Hardware shadow copy technology please see the VSS SDK.
The import process is given below:
- Create the shadow copy set on machine A (the production server). This will not expose any shadow
copy devices on this machine.
VSHADOW -p -t=bc1.xml
- Copy the backup components document on machine B
- Import the shadow set on machine B. This will surface the created devices on this machine
VSHADOW -i=bc1.xml
Optionally, you could expose these shadow copies as drive letters or mount points. Also, you could
potentially break the shadow set to make the new shadow copy volumes read-write.
To automate the shadow set management process you might use the -script option to generate the CMD
script containing the shadow copy IDs. Then, you can copy the generated script along with the backup
components on the other machine.
As an example we present below a scriptable shadow creation, expose and break involving transportable
shadow copies:
1) Create the shadow copy set on machine A (the production server). This will not expose any
shadow copy devices on this machine. Specify also the -script option to generate the script
containing the proper environment variable definitions.
VSHADOW -p -t=bc1.xml -script=sc1.cmd
2) Copy the backup components document and the generated script on machine B
3) Import the shadow set on machine B. This will surface the created devices on this machine
VSHADOW -i=bc1.xml
4) Now, run the generated script to get the proper environment variables set up. The shadow set ID
goes into the variable named VSHADOW_SET_ID. The shadow ID for the first volume specified
during creation goes into the VSHADOW_ID_1 variable, and so on.
Sc1.cmd
5) Expose the shadow copies to certain drive letters on machine B. This will surface the created
shadow copy devices on this machine.
RD /s/q c:\mount_point
MD c:\mount_point

Page 8 of 16

The VSHADOW sample client

Copyright 2004, Microsoft Corporation.

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.

Writer and component related topics

VSHADOW allows certain writers in the system to participate in the shadow copy creation or restore
process. For more details on writers and writer components please see the VSS SDK.
By default, all writers will participate in shadow copy creation unless the option -nw is used. Also, you can
use the -wx option to selectively exclude certain writers from the creation or restore process.

Selecting volumes for shadow copy creation

Before the shadow copy creation, you might run a VSHADOW -wm or even VSHADOW -wm2 command to
discover the affected paths and volumes for each component. Then, you should include enough volumes in
the shadow set such that the interesting writers\components are being involved.
Remember that if you do not include the relevant volumes, the shadow copy will not contain the specified
writers.
You can use the -wi option to verify that a certain writer/component gets included. See below for more
details.

Verification of writer/component inclusion

During creation, you can test whether certain writers or components were included in the backup
components through the -wi option. This option has a similar syntax with the -wx option. Similarly, you
can use the same option to verify if certain components are restored.
Important note: The -wi command does not actually enforce the inclusion of the component it just
verifies that the component/writer is already included automatically by specifying the correct volumes in the
shadow copy set. Ultimately, you must specify the correct volumes such that the desired components will get
included. Please see the chapter titled Component Selection in VSHADOW for more details on the
component selection algorithm.
This option has two operational modes. First, with the -wi option, you can verify whether a certain
component is included in the backup. There are various syntax options here. Some examples:
VSHADOW
options}
VSHADOW
VSHADOW
VSHADOW

wi=WriterName:\LogicalPath\ComponentName

{creation

wi="Writer name:\LogicalPath\ComponentName" {creation options}

wi={WriterID}:\LogicalPath\ComponentName
{creation options}
wi={InstanceID}:\LogicalPath\ComponentName {creation options}

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

{snapshot creation options}

{snapshot creation options}

The VSHADOW sample client

VSHADOW wi={WriterID}
VSHADOW wi={InstanceID}

Copyright 2004, Microsoft Corporation.

{snapshot creation options}
{snapshot creation options}

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

{snapshot creation options}

{snapshot creation options}
{snapshot creation options}

The VSHADOW sample client

VSHADOW wx={InstanceID}

Copyright 2004, Microsoft Corporation.

{snapshot creation options}

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

wx="Writer name:\LogicalPath\ComponentName" {creation options}

wx={WriterID}:\LogicalPath\ComponentName
{creation options}
wx={InstanceID}:\LogicalPath\ComponentName {creation options}

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

Component selection during shadow copy creation

The sample code has a simple component selection algorithm. Based on the given set of volumes, it will
safely select the maximal set of components from all writers, such that no selected component (implicitly or
explicitly) will have its file descriptors on volumes not in the shadow set. In other words if the component X
will have file descriptors on volume Y: outside the shadow copy set, then this component wont be selected.
Definitions:
- X is ancestor of Y = Y is descendent of X = including component X implies including component Y.
- Directly excluded component = component that cannot be included since one of its file groups has
data outside the shadow copy set.
- Excluded component = component that cannot be included since one of its descendents is directly
excluded.
- Non-excluded component = component that is not excluded. Note that this component is not
necessarily included.
- Included component = All components that are non-excluded and are equal or descendants of:
o Either a selectable non-excluded component.
o Or a non-selectable non-excluded top-level component.
- Explicitly included component = non-excluded component on which
IVssBackupComponents::AddComponent will be called. This component should be either:
o A selectable, non-excluded component with no explicitly included ancestors.
o Or a top-level non-selectable non-excluded component.
- Implicitly included component = descendent of an explicitly included component.
- X is root in list L = X does not have ancestors in list L.
General VSS selection rules:
- You can call AddComponent only on selectable components and/or on top-level non-selectable
components.
- If you explicitly include a component (i.e. call AddComponent on it), then all descendents are
implicitly included. You are not allowed to call AddComponent on one of its descendents.
- If at least one component is included from a writer X then all top-level non-selectable components
from this writer must be explicitly included as well.
The component selection verification algorithm used by VSHADOW:
- First we discover all directly excluded components. These are components that have file groups
containing data outside the volumes that have to be shadow copied.

Page 11 of 16

The VSHADOW sample client

-

Copyright 2004, Microsoft Corporation.

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.

Limitations of this algorithm:

- The component consistency verification algorithm in VSHADOW has two limitations.
o The algorithm will not follow component dependencies. In other words, if component X from
writer A depends on component Y from writer B, and the component Y will be excluded, then
this does not necessarily means that the component X will be excluded as well. However,
the writer A might fail since its dependent component Y was not selected during the backup.
o The algorithm will not follow mount point chains. In other words, if component X defines a
File Descriptor including all recursive files under a certain directory c:\foo, then VSHADOW
will not verify if all the mount points recursively mounted under C:\ are included in the
shadow copy set. Therefore the component will still be added to the backup even if certain
parts of the reported namespace are not shadow copied.

Component selection for restore

In the case of restore, the component selection is done only on the components already present (backed-up)
in the backup components document. By default, all components from the backup components document
are considered for restore, unless -wx is used.
A backed-up component can be restored through VSHADOW only if the associated writer is already running
on the machine. The existing components on the currently-running writers are ignored.
The exclusion/inclusion rules mentioned above for the shadow creation case apply in a similar manner
during restore. A previously backed-up component can be specifically excluded with the -wx option. Also,
you can verify the selectability state of a certain component during restore through the -wi option.
Limitations of this algorithm:
The current VSHADOW code has only minimal restore support. The code does not offer any way to do
partial restores, new targets, alternate targets, subcomponent selection or other advanced restore
functionality that can be found in a true requestor.

Test scripts for shadow copy management

These tests test for various options available for vshadow.exe. These include tests relating to shadow copy
creation, deletion and query with or without writers involved. Hardware provider tests specifically test for
break and transportable snapshot features.

Page 12 of 16

The VSHADOW sample client

Copyright 2004, Microsoft Corporation.

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:

Test scripts for backup and restore

Page 13 of 16

The VSHADOW sample client

Copyright 2004, Microsoft Corporation.

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.

What are the limitations of VSHADOW?

To keep the sample code small and simple to read, we choose to not implement some advanced
requirements of a true VSS requestor. Please see the BETEST sample code from the VSS SDK for a fullyimplemented VSS requestor.

Page 14 of 16

The VSHADOW sample client

-

Copyright 2004, Microsoft Corporation.

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.

List of files in the VSHADOW project

Directory
.\SRC

.\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.

The VSHADOW sample client

{xp|ws03}
.\LIB\{xp|ws03}

VShadow.pdb
vssapi.lib
vss_uuid.lib

.\tests\shadow_creation
.\tests\backup_restore

.\

readme.doc
VShadow.sln

Copyright 2004, Microsoft Corporation.

External dependency: VSS libraries (also included in the VSS

SDK)
Sample CMD-based test scripts for shadow copy creation,
query, deletion, import, expose, break. A subset of these
scripts is also available for Windows XP
Sample CMD-based test scripts for backup and restore of a
SQL database with VSHADOW. To exercise the VSHADOW
backup/restore scripts you also need either SQL Server 2000
or MSDE installed on the machine.
This document
Visual Studio solution for VSHADOW

Building the sample code

Build steps:
1) Install Visual C++ 2003
2) Install Platform SDK (see this link for download location)
3) Install Platform SDK within Visual Studio (see this link for instructions)
4) Load and build the VSHADOW.SLN solution from Visual Studio. The requestor can be built in four
flavors
1. Debug-XP and Release-XP (targeting Windows XP)
2. Debug-Server and Release-Server (targeting Windows Server 2003 and future versions of
Windows)
Below we present the settings used by us to create the VSHADOW project. You do not have to specify these
settings these are already present in the VSHADOW project:
1) Create a new project (Win32 console application with ATL support)
2) Create four configurations (Debug-XP, Release-XP, Debug-Server and Release-Server)
3) Add the CPP/H files to the project
4) In the project settings, for each configuration:
a. In the General tab settings, select Use Unicode Character Set.
b. In C/C++, General tab, add additional includes for this project:
i. "$(SolutionDir)\inc\ws03" for Server projects
ii. "$(SolutionDir)\inc\xp" for XP projects
c. In the C/C++, Preprocessor tab, add these additional macros:
i. For XP configurations: _ATL_NO_DEBUG_CRT;_WIN32_WINNT=0x500;VSS_XP
ii. For Server configurations:
_ATL_NO_DEBUG_CRT;_WIN32_WINNT=0x500;VSS_SERVER
d. In the Linker, General tab, add additional library directories
i. "$(SolutionDir)\lib\xp\i386" for XP projects
ii. "$(SolutionDir)\lib\xws03\i386" for Server projects
e. In the Linker, Input tab, add vssapi.lib and vss_uuid.lib as additional library dependencies
Important note: Since the VSS API is dependent on the operating system type, we defined two macros that
to differentiate between the two XP/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

Page 16 of 16