This tool serves as a sample VSS application that demonstrates various tasks performed by a regular VSS requestor. VSHADOW.EXE also offers a simple command-line interface for VSS management, including shadow copy creation, deletion and query.
This sample code must be compiled with Visual Studio 2005.
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.
VSHADOW [optional list of flags] {list of volumes} Flags: -p - Creates persistent shadow copies -nw - Creates shadow copies without involving writers -ad - Creates Differential Hardware shadow copies -ap - Creates Plex Hardware shadow copies -scsf - Creates Shadow Copies for Shared Folders (Client accessible) -wi={writer} - Verifies that a certain writer/component is included -wx={writer} - Excludes a certain writer/component from the shadow copy -t={file.xml} - 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. -bc={file.xml} - 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. -script={file.cmd} - Generates a CMD file containing environment variables related to created shadow copies (the shadow copy IDs, the shadow copy set ID, etc) -exec={command} - Executes a shell command between the shadow set creation and VSHADOW program exit. Useful for non-persistent shadow copies. -wait - Wait for the user interaction before exiting. This will keep alive non- persistent shadows. -tracing - Verbose output - useful for diagnosis.
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.
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 - Wait for the user interaction before exiting. This will keep alive non- persistent shadows. -tracing - Verbose output - useful for diagnosis.
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.
VSHADOW { -q | -qx={SnapSetID} } Flags: -q - List all shadow copies in the system -qx={SnapSetID} - List all shadow copies in this set -s={SnapID} - List the snapshot with the given ID
The implementation uses either QuerySnapshots or GetSnapshotProperties APIs to display the properties of the given set of shadow copies.
VSHADOW { -da | -dx={SnapSetID} | -ds={SnapSetID} } Flags: -da - Deletes all shadow copies in the system -dx={SnapSetID} - Deletes all shadow copies in ths set -ds={SnapID} - Deletes this shadow copy
The -da option requires user confirmation.
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).
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.
VSHADOW { -b={SnapSetID} | -bw={SnapSetID} } Flags: -b={SnapSetID} - Break the given shadow copy set into standalone read-only volumes. -bw={SnapSetID} - Break the shadow copy set into standalone writable volumes
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.
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.
VSHADOW -el={SnapID},LocalEmptyDirectory VSHADOW -el={SnapID},UnusedDriveLetter
Let’s 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
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 -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.
VSHADOW -er={SnapID},UnusedShareName VSHADOW -er={SnapID}, UnusedShareName,PathFromRootOnShadow
Let’s 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. Let’s 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
These commands are useful to detect potential failed writers, and to enumerate their components.
VSHADOW -ws VSHADOW -wm VSHADOW -wm2
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.
VSHADOW [optional list of flags] -r={file.xml} VSHADOW [optional list of flags] -rs={file.xml} Flags: -wi={writer} - Verifies that a certain writer/component is included in restore -wx={writer} - Excludes a certain writer/component from the restore -exec={command} - Executes a file restore command between the Pre-restore and Post- restore events that were sent to the writers. -tracing - Verbose output - useful for diagnosis.
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:
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:
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 documentation 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.
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:
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
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:
dir > c:\somefile.txt VSHADOW -p -nw -script=SETVAR1.cmd c: call SETVAR1.cmd copy %VSHADOW_DEVICE_1%\somefile.txt c:\somefile_bak.txt
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.
First, you need two separate machines running Windows Server 2008. 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 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 (vsssampleprovider) that can be used for simulating hardware shadow copies. For more information on VSS Hardware shadow copy technology please see the VSS documentation.
The import process is given below:
VSHADOW -p -t=bc1.xml
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:
VSHADOW -p -t=bc1.xml -script=sc1.cmd
VSHADOW -i=bc1.xml
Sc1.cmd
RD /s/q c:\mount_point MD c:\mount_point VSHADOW -el=%VSHADOW_ID_1%,c:\mount_point
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.
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 online documentation.
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.
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.
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 -wi=WriterName:\LogicalPath\ComponentName {creation options} VSHADOW -wi="Writer name:\LogicalPath\ComponentName" {creation options} VSHADOW -wi={WriterID}:\LogicalPath\ComponentName {creation options} VSHADOW -wi={InstanceID}:\LogicalPath\ComponentName {creation options}
Additionally, you can verify if all components from a certain writer will be included:
VSHADOW -wi=WriterName {snapshot creation options} VSHADOW -wi="Writer name" {snapshot creation options} VSHADOW -wi={WriterID} {snapshot creation options} VSHADOW -wi={InstanceID} {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 3.0 - Volume Shadow Copy sample client Copyright (C) 2005 Microsoft Corporation. All rights reserved. (Option: List writer metadata) (Gathering writer metadata...) Initialize writer metadata ... Listing writer metadata ... * WRITER 'MSDEWriter' - WriterId = {01b5efaa-1b5f0ba-6f73c-6f7306f790-6f7286f73c6f73c1bd483c6f73c6f73c} - 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:
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 {snapshot creation options} VSHADOW -wx="Writer name" {snapshot creation options} VSHADOW -wx={WriterID} {snapshot creation options} VSHADOW -wx={InstanceID} {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 -wx=WriterName:\LogicalPath\ComponentName {creation options} VSHADOW -wx="Writer name:\LogicalPath\ComponentName" {creation options} VSHADOW -wx={WriterID}:\LogicalPath\ComponentName {creation options} VSHADOW -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”
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 won’t be selected.
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.
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.
File name | Description |
macros.h | Useful macros |
create.cpp | VSS shadow copy creation code |
delete.cpp | VSS shadow copy deletion code |
break.cpp | VSS shadow copy break code |
query.cpp | VSS shadow copy query code |
stdafx.cpp | Precompiled header (general declarations) |
stdafx.h | |
tracing.cpp | Very simple tracing/logging class |
tracing.h | |
util.h | Utility routines (string conversion, volume APIs, etc) |
shadow.cpp | VSHADOW command-line specific code (CLI parsing, usage routine, etc) |
shadow.h | |
vssclient.cpp | Declaration/definition of the VSS API wrapper class. |
vssclient.h | |
Writer.h | VSS writer metadata wrappers (writer, component, file descriptor, etc) |
Select.cpp | Component selection code. |
writer.cpp | Implementation of VSS writer metadata wrappers |
vshadow.vcproj | Visual Studio project file |
readme | This document |
VShadow.sln | Visual Studio solution for VSHADOW |
Building the Visual Studio 2005 project will produce vshadow.exe. Start a cmd.exe window running as a local administrator, and run this program to see the list of available commands.
Building solution outside of SDK directory requires MSSdk environment variable defined or project file updated with paths to includes and libraries. For more information about MSSdk environment variable, please see the SetEnv.Cmd script in bin subdirectory inside SDK installation path.
Itanium architecture is available as a target for server SKUs only. Appropriate compiler is required.
Visual Studio 2005 solution is designed to work in Visual Studio 2008 as well after initial conversion performed by the IDE.
Building in Visual Studio 2005 against SDK libraries may require manual reconfiguration of Visual Studio 2005 directories configuration if you encounter linker errors related to uuid.lib. To do that, please select Tools > Options in the main menu. Navigate to Projects and Solutions > VC++ Directories branch and select "Library files" for your desired architecture from the "Show directories for" dropdown menu. SDK path will vary depending on the installation directory. By default it is c:\Program Files\Microsoft SDKs\Windows\v7.0\Include. Select and move this directory down the list using "Line Down" button in the upper right corner of the dialog.