A developer's view on VSS for SMB File Shares

Article
07/17/2012

VSS for SMB File Shares is an extension to the existing VSS infrastructure which consists of four parts:

Component Name	Type	Binary	Function
File Share Shadow Copy Provider	VSS File Share Provider	Fssprov.dll	Loaded by VSS service as In-Proc COM server. It is installed on all Windows Server 2012 Editions by default.
File Share Shadow Copy Agent	File Server VSS proxy requestor	FssAgent.dll	Implements FssAgent RPC server. It is an optional Windows Server 2012 file server role service.
New VSS API	VSS API	Vssapi.dll	Enhance VSS infrastructure to support UNC share paths.
New File Server Remote VSS Protocol	MS-FSRVP RPC protocol	N/A	Open protocol for 3^rd party plug-in.

In this post I want to look at VSS for SMB File Shares from a developers point of view and how to support it with minimal changes to 3^rd party VSS requestors, writers and providers, as well as look at how to investigate backup issues with betest, vsstrace and Microsoft Netmon trace tools.

Hopefully you have already read the blog covering technical overview and deployment scenarios of VSS for SMB File Shares. For more technical details of this feature, please refer to Molly Brown’s talk at Storage Developers Conference 2012 and the MS-FSRVP protocol document.

VSS changes

The summary of backup application related VSS changes are listed below.

VSS Requestor
- COM Security
- Support UNC path
- UNC Path normalization
VSS Writer
VSS Providers

VSS requestor

Requestor is one of the key VSS components that drives the application consistent shadow copy creation and backup/restore.

COM Security

As a COM client to VSS coordinator service, the VSS requestor compatible with this feature must satisfy the following security requirements:

Run under a user account with local administrator or backup operator privilege on both application server and file servers.
Enable Impersonation and Cloaking so that the user token running backup application can be authenticated on the file server.

Below is a sample code to achieve this. More detail can be found in Security Considerations for Requestors.

// Initialize COM security.

CoInitializeSecurity(

NULL, // PSECURITY_DESCRIPTOR pSecDesc,

-1, // LONG cAuthSvc,

NULL, // SOLE_AUTHENTICATION_SERVICE *asAuthSvc,

NULL, // void *pReserved1,

RPC_C_AUTHN_LEVEL_PKT_PRIVACY, // DWORD dwAuthnLevel,

RPC_C_IMP_LEVEL_IMPERSONATE, // DWORD dwImpLevel,

NULL, // void *pAuthList,

EOAC_STATIC_CLOAKING, // DWORD dwCapabilities,

NULL // void *pReserved3

);

Support UNC path

Prior to this feature, VSS only supported requestor adding shadow copies of data stored on local volume. With the new “File Share Shadow Copy Provider” available by default on all Windows Server 2012 editions, VSS now allows adding SMB UNC share path to a shadow copy set by calling the same IVssBackupComponents::AddToSnapshotSet method. Below is a simple code snippet to add a SMB UNC share path \\server1\gueststo the shadow copy set.

VSS_ID shadowCopySetId = GUID_NULL;

VSS_ID shadowCopyId = GUID_NULL;

CComPtr <IVssBackupComponents> spBackup;

LPWSTR pwszPath == L“\\server1\guests”

spBackup = CreateVssBackupComponents (VssBackupComponents);

spBackup->StartSnapshotSet(&shadowCopySetId);

spBackup->AddToSnapshotSet(pwszPath, GUID_NULL, &shadowCopyId);

…

UNC Path Normalization

Similar to local volume, uniquely identify a UNC share path in a shadow copy set is key to VSS-based shadow copy creation and backup/recovery. An UNC share path is composed of two parts: server name and share name. For the same share, the server name part of a UNC path can be configured in writer component in different formats below with many variations.

Host name
FQDN (Fully Qualified Domain Name)
IPv4
IPv6 or IPv6 literal format

This feature adds a new method IVssBackupComponents4::GetRootAndLogicalPrefixPaths that normalizes a given UNC share path to its unique root path and logical prefix format. The unique root path and logical prefix path are designed to be used for shadow copy creation and backup/restore file path formation, respectively.

Note that a VSS requestor need to:

Call IVssBackupComponents::AddToSnapshotSet with unique root path of UNC share in hostname or FQDN format but not IPv4 or IPv6 address format.

If a UNC share path is in IPv4 or IPv6 address format, its root path must be normalized into hostname or FQDN by calling IVssBackupComponents4::GetRootAndLogicalPrefixPaths.
Consistently normalize the file share UNC path into either host name or FQDN format in the same shadow copy set before IVssBackupComponents::AddToSnapshotSet.
Don’t call mix hostname or FQDN format in the same shadow copy set. Note the default root path format returned is hostname format. You can specify the optional 4^th parameter to require FQDN format in the returned unique root path.
IPv4/IPv6 DNS reverse lookup must be configured appropriately on DNS infrastructure when normalizing UNC share path in IPv4/IPv6 format. Below are the examples to determine if your DNS server enables reverse IP address lookup for the specific address:

Example of IPv4 reverse look up is enabled on DNS. In this case, you can find the highlighted hostname/FQDN is resolved from IP address.

F:\>ping -a 10.10.10.110

Pinging filesever.contoso.com [10.10.10.110] with 32 bytes of data:

Reply from 10.10.10.110: bytes=32 time=1ms TTL=57

Example of IPv6 reverse lookup is not configured for 2001:4898:dc3:1005:21c:c4ff:fe68:e88. In this case, you can find that the hostname/FQDN cannot be resolved as the highlighted part is still IPv6 address.

F:\>ping -a 2001:4898:dc3:1005:21c:c4ff:fe68:e88

Pinging 2001:4898:dc3:1005:21c:c4ff:fe68:e88 with 32 bytes of data:

Reply from 2001:4898:dc3:1005:21c:c4ff:fe68:e88: time=3ms

Reply from 2001:4898:dc3:1005:21c:c4ff:fe68:e88: time=1ms

If your DNS server does not have IPv6 DNS reverse lookup configured, you can manually add the IP address to hostname/FQDN mapping to your local DNS cache directly. To achieve this, open %SystemRoot%\system32\drivers\etc\hosts with notepad.exe from an elevated command window and add one line for each IP address to hostname/FQDN mapping as shown below. Most of the deployments we tested have IPv4 reverse DNS lookup available. But not all of them have IPv6 DNS reverse lookup configured.

2001:4898:2a:3:6c94:5149:2f9c:f083 fileserver.contoso.com

2001:4898:2a:3:6c94:5149:2f9c:f083 fileserver

To unify the normalization of all VSS supported paths, this API also supports

DFS-N path pointing to another physical server, which returns the fully evaluated physical share path on the DFS target server.
Local volume, which returns the results of GetVolumePathName and GetVolumeNameForVolumeMountPoint on the input path.

Below is a sample requestor code snippet to illustrate how backup applications use IVssBackupComponentsEx4::GetRootAndLogicalPrefixPaths to normalize root path and logical prefix path for shadow copy creation and backup of files under DFS-N path.

#define CHK_COM(X) \

hr = X; \

if (FAILED(hr)) \

wprintf(L"COM Call %S failed: 0x%08lx", #X, hr );\

goto _Exit;\

}

…

CComPtr <IVssBackupComponents> spBackup;

CComPtr<IVssBackupComponentsEx4>spBackup4;

CComPtr <IVssAsync> spAsync;

VSS_ID shadowCopySetId = GUID_NULL;

VSS_ID shadowCopyId = GUID_NULL;

VSS_SNAPSHOT_PROP shadowCopyProp;

// GatherWriterMetadata and metadata enumeration are not shown below.

// Instead, we assumes one writer component path to be shadow copied and backed up.

// \\dfsworld\logical\path\guests is a DFS-N link to \\server1\guests

// vm1 is a directory under \\server1\guests which contains the vhd file vm1.vhd that needs to

// be backed up.

LPWSTR pwszWriterComponentPath = L“\\dfsworld\logical\path\guests\vm1”;

LPWSTR pwszWriterComponentFileSpec = L“vm1.vhd”;

LPWSTR pwszRootPath = NULL;

LPWSTR pwszLogicalPrefix = NULL;

HRESULT hr = S_OK;

CHK_COM(CreateVssBackupComponents (&spBackup));

CHK_COM(spBackup->SafeQI(IVssBackupComponentsEx4, &spBackup4));

// The caller must free the pwszRootPath and pwszLogicalPrefix strings allocated by GetRootAndLogicalPrefix()

CHK_COM(spBackup->GetRootAndLogicalPrefixPaths(writerComponentPath, &pwszRootPath, &pwszLogicalPrefix));

// pwszRootPath == “\\server1\guests”

// pwszLogicalPrefix == “\\dfsworld\logical\path\guests”

CHK_COM(spBackup->StartSnapshotSet(&shadowCopySetId));

CHK_COM(spBackup->AddToSnapshotSet(rootPath, GUID_NULL, &shadowCopyId));

CHK_COM(spBackup->DoSnapshotSet(&spAsync));

CHK_COM(spAsync->Wait());

CHK_COM(spBackup->GetSnapshotProperties(shadowCopyId, &shadowCopyProp));

// Build snapshot relative path for file copy

// 1. Initialize it to shadow copy share path \\server1\guests@{guid}

CComBSTR shadowCopyPath = shadowCopyProp->m_wszSnapshotDevicePath;

// 2. Get the relative path below the logical prefix path, “\vm1\vm1.vhd”

//This is based on the logical prefix path returned from GetRootAndLogicalPrefixPaths,

CComBSTR relativePath = writerComponentPath + wcslen(logicalPrefix);

// 3. Append the relativePath and the wrierComponentFileSpec \\server1\guest@{guid}\vm1\

shadowCopyPath += relativePath;

// For each file (backupItem) that matches the file spec under the shadowCopyPath, copy the file to backup store

// \\server1\guest@{guid}\vm1\vm1.vhd

CComBSTR backupItem = shadowCopyPath+writerComponentFileSpec;

HANDLE h = CreateFile(

backupItem,

…

);

// BackupRead and Copy from backItem

…

_Exit:

// The caller must free the string allocated by GetRootAndLogicalPrefix()

if (pwszRootPath!=NULL)

CoTaskMemFree(&pwszRootPath);

If (pwszLogicalPrefix!=NULL)

ContaskMemFree(&pwszLogicalPrefix);

VSS writer

There is no change needed from VSS writer to support this feature as long as the application itself allows storing application data on SMB share.

VSS provider

On application server, the new file share shadow copy provider handles the file share shadow copy life cycle management. There is no change needed from existing VSS software/hardware provider to support this feature.

Developer tools

Betest for backup/restore Hyper-V over SMB

BETest is a VSS requester that tests advanced backup and restore operations. It is included in the Microsoft Windows Software Development Kit (SDK) since Windows Vista and later. However, only the BETest in Windows Server 2012 SDK has been extended to support this feature. Full detail about betest can be found in the BETest document.

Below we give an example to online backup and restore Hyper-V VM running over SMB shares. Please refer to the Hyper-V over SMB guide to configure Hyper-V over SMB.

1. Download Windows 8 SDK which includes BETest tool.

2. Get the VMId of the Hyper-V VM to be backed up by running powershell cmdlet. Assuming the VM to be backed up is named test-vm10, you run:

PS C:\test> get-vm -name test-vm10|select vmid

VMId

----

c8a460ae-8aa2-4219-8c4f-532479fb854a

3. Create the backup component file vm10.xml for backup.

The Hyper-V writer ID is a GUID constant {66841cd4-6ded-4f4b-8f17-fd23f8ddc3de}. Each VM is handled by Hyper-V writer individually as a separate component with a componentName equals to its VMId. To select more VMs for backup, you can repeat step 2 to get all the VMIDs and put each into <Component> </Component>.

</Writer>

</BETest>

4. Create a shadow copy and Full backup based on the components selected by vm10.xml.

Upon completion of execution, the application consistent Hyper-V VM VHD and VM configuration file for VM (test-vm10) will be snapshotted and copied to backup destination specified with “/D” parameter (C:\backupstore). A new backup document vm10backup.xml specified by /S parameter will be created as well. It will be used with the file in the backup destination for restore later.

betest /b /V /T FULL /D C:\backupstore /X vm10.xml /S vm10backup.xml

If you just want to create the snapshot for testing purpose without waiting for the long file copying, you can just run the following command without /D and /S parameters like below.

betest /b /V /T FULL /X vm10.xml

During step 4, the betest output includes lots of writer information during shadow copy creation and backup. The key to determine if the backup succeeds or not is to check writer status at the end of the output as highlighted below after backup complete. You need to rerun step 4 until you get an application consistent backup indicated by STABLE writer state after backup. If you keep getting errors during step 4, vsstrace and netmon traces discussed below are the most useful tools to help investigation.

status After Backup Complete (14 writers)

Status for writer Task Scheduler Writer: STABLE(0x00000000)

Status for writer VSS Metadata Store Writer: STABLE(0x00000000)

Status for writer Performance Counters Writer: STABLE(0x00000000)

Status for writer Microsoft Hyper-V VSS Writer: STABLE(0x00000000)

Status for writer System Writer: STABLE(0x00000000)