The VSHADOW sample client

Introduction

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.

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

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.

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               - Wait for the user interaction before exiting. This will keep alive non-
                          persistent shadows.
    -tracing            - 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} }

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

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

Flags:
    -da                 - Deletes all shadow copies in the system
    -dx={SnapSetID}     - Deletes all shadow copies in ths set
    -ds={SnapID}        - Deletes this shadow copy

Notes

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

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

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

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

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

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

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

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

Notes

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 has just happened (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 vshadow 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 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.

Other command-line flags

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:

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

How to manage transportable shadow copies

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:

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

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

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         {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”

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 won’t be selected.

Definitions

General VSS selection rules

The component selection verification algorithm used by VSHADOW

Limitations of this algorithm

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.

List of files in the VSHADOW project

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 VSHADOW project

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.