Product Documentation

c-treeACE V10.0 Update Guide

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. A FULL CONSISTENCY VSS backup of FairCom database files will be created, which is comparable to cleanly shutting down the FairCom server and then backing up all files.

For application files that are under full transaction control, a FULL CONSISTENCY VSS backup is more time-consuming and invasive than strictly required. Application files with the ctTRNLOG property are under full transaction control. If full transaction controlled files and the database transaction logs (L*.FCS and S0*.FCS) are included in backups, a normal database automatic recovery takes place at startup and will properly restore CRASH CONSISTENT backed up data. Do NOT enable VSS_WRITER YES in ctsrvr.cfg, on application files that are under full transaction control.

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

  • The FairCom VSS writer is compatible with the backup utilities provided in the server versions of Windows.
  • The Windows backup software provided in desktop versions of Windows (the Enterprise edition of Windows 7 and Windows 8) is not a VSS-compatible backup provider and therefore will not work with the FairCom VSS writer.
  • Windows Server backup (2008 & 2012) is a VSS provider and works with the FairCom VSS writer.
  • Acronis Backup has been tested on Windows 7 (both 32-bit and 64-bit) and works correctly with the FairCom VSS writer when configured with ctsrvr.dds.
  • The Novastor backup utility has been tested on non-server versions of Windows and works correctly with the FairCom VSS writer when configured with ctsrvr.dds.
  • Other third-party backup utilities may work with the FairCom VSS writer if they are VSS-compatible backup providers. Please check with the manufacturer of your backup utility for information about VSS compatibility.

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 faircom.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 (this can be enabled dynamically on the fly with server administrator utilities):

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 following SQL built-in procedures can enable VSS Writer support:

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

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

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");

TOCIndex