Windows Volume Shadow Copy Service (VSS) Writer

Previous Topic

Next Topic

Windows Volume Shadow Copy Service (VSS) Writer

The VSS writer has been added as an integral component of the c-treeACE Server for Windows. This component is supplied as a Windows dynamic link library (c-treeACEVSSWriter.dll) and can be optionally loaded by c-treeACE at startup. (An executable, c-treeACEVSSWriter.exe, is also supplied for testing purposes, however, not intended for production use.)

VSS Configuration

VSS_WRITER YES

With this option enabled, c-treeACE loads the Volume Shadow Copy Service (VSS) writer DLL (c-treeACEVSSWriter.dll) and initializes the VSS writer when the server starts.

Note: VSS backups require the Volume Shadow Copy service to be running. If this Windows service is set to start manually or is off by default, it needs to be started before VSS backup will work.

The following message is logged in CTSTATUS.FCS indicating the VSS writer has been started:

Mon Sep 13 14:11:27 2010

- User# 00001 VSS Init: Successfully started the VSS writer.

If you run the command “vssadmin list writers” on a machine with c-treeACE Server running and a properly configured VSS, the list should include c‑treeACEVSSWriter.

Compatibility Notes

User Permissions

FairCom VSS Writer is intended to be run by users with Administrator permissions. To avoid permission issues when running the VSS Writer with a user that is not an Administrator, you must perform the following operations on the Windows registry:

  1. Run the Windows regedit command.
  2. Browse to find the Key: HKEY_LOCAL_MACHINE>SYSTEM>CurrentControlSet>Services>VSS>VssAccessControl
  3. Insert a new REG_DWORD value with the following syntax DOMAINNAME\USERNAME. For example, if your domain is MYDomain and your user name is User, enter: MYDomain\User
  4. Set the newly created key to the hexadecimal value of 1.
  5. Restart the computer to apply the changes.

Files to Be Backed Up

The VSS writer needs a list of files that are considered as under the server's control. This information must be located in the file ctsrvr.dds residing in the server's working directory (where the ctreesql.exe is located). For the VSS backup, only entries between !FILES and !END are relevant. There is no directory recursion, so wildcards will not be matched in subdirectories.


!FILES

C:\FairCom\ctreeSDK\ctreeAPI\bin.sql\ctreeSQL.dbs\test1.dat

C:\FairCom\ctreeSDK\ctreeAPI\bin.sql\ctreeSQL.dbs\test1.idx

ctreeSQL.dbs\*.dat

ctreeSQL.dbs\*.idx

ctreeSQL.dbs\SQL_SYS\*

!END

This information tells the backup utility which files are under c-treeACE control. If the set of files being backed up does not intersect with the set of files listed in ctsrvr.dds, the VSS service does not interact with c-treeACE VSS writer, resulting in an invalid backup of any files open by the server.

While testing, it is recommended to run the c-treeACE SQL Server with DIAGNOSTICS VSS_WRITER in ctsrvr.cfg. When the VSS writer is correctly configured, you should see entries logged to CTSTATUS.FCS like those listed in VSS Diagnostic Logging.

VSS Diagnostic Logging

The following c-treeACE configuration option enables VSS writer diagnostic logging:

DIAGNOSTICS VSS_WRITER

When enabled, the VSS writer logs diagnostic messages to CTSTATUS.FCS. These messages indicate the sequence of operations to which the VSS writer is responding. Some examples are shown below:


Tue Sep 14 15:44:05 2010

- User# 00016 VSS Diag: [0x1098] c-treeACEVSSWriter::OnIdentify called

Tue Sep 14 15:44:07 2010

- User# 00016 VSS Diag: [0x1098] c-treeACEVSSWriter::OnPrepareBackup called

Tue Sep 14 15:44:07 2010

- User# 00016 VSS Diag: [0x1098] (+) Component: CtreeACE

Tue Sep 14 15:44:07 2010

- User# 00016 VSS Diag: [0x1098] c-treeACEVSSWriter::OnPrepareSnapshot called

Tue Sep 14 15:44:07 2010

- User# 00016 VSS Diag: [0x1098] c-treeACEVSSWriter::OnFreeze called

Tue Sep 14 15:44:07 2010

- User# 00016 VSS Diag: [0x1098] QuietCtree(ctQTblockALL | ctQTflushAllFiles)...

Tue Sep 14 15:44:08 2010

- User# 00016 VSS Diag: [0x1098] c-treeACEVSSWriter::OnThaw called

Tue Sep 14 15:44:08 2010

- User# 00016 VSS Diag: [0x1098] QuietCtree(ctQTunblockALL)...

Tue Sep 14 15:44:08 2010

- User# 00016 VSS Diag: [0x1098] c-treeACEVSSWriter::OnPostSnapshot called

Tue Sep 14 15:44:10 2010

- User# 00016 VSS Diag: [0x1098] c-treeACEVSSWriter::OnIdentify called

Tue Sep 14 15:44:25 2010

- User# 00016 VSS Diag: [0x1098] c-treeACEVSSWriter::OnIdentify called

Tue Sep 14 15:44:26 2010

- User# 00016 VSS Diag: [0x1098] c-treeACEVSSWriter::OnBackupComplete called

Tue Sep 14 15:44:26 2010

- User# 00016 VSS Diag: [0x1098] c-treeACEVSSWriter::OnBackupShutdown called

Note: The VSS writer always logs error messages to the Windows event log, even if the DIAGNOSTICS VSS_WRITER option is not specified in the configuration file.

Dynamic API Interaction

The SetConfiguration(), ctSETCFG() API function can be used to change VSS configuration dynamically.

Examples

If the c-treeACE VSS writer is not running, the following call starts it:

ctSETCFG(setcfgVSS_WRITER, "YES");

If the c-treeACE VSS writer is running, the following call stops it:

ctSETCFG(setcfgVSS_WRITER, "NO");

The following call enables VSS writer diagnostic logging:

ctSETCFG(setcfgDIAGNOSTICS, "VSS_WRITER");

The following call disables VSS writer diagnostic logging:

ctSETCFG(setcfgDIAGNOSTICS, "~VSS_WRITER");

The following SQL built-in procedure can enable VSS Writer support:

call fc_set_sysconfig('vss_writer', 'YES');

call fc_set_sysconfig('diagnostics', 'VSS_WRITER');