This wide- and large- screen layout may not work quite right without Javascript.

Maybe enable Javascript, then try again.

Chuck Kollars` Personal Home Visual Source Safe

Backing Up VSS

If you want to closely examine the charts/pictures/code on this page but they are not easily viewable on your device, note the web address and return to view it later from a device with a larger display screen.

This material on VSS is an archive from fall 1998, about two decades ago. First I changed jobs so I no longer had any association with VSS. Then after a couple more years I changed careers completely so I wasn't associated with high tech at all. Then after even more years I retired altogether. I've left the VSS material on this site for use by others, even though I no longer remember exactly what it's about, or even understand some of it.

VSS continues to be used and to provide integration with other products, even though the VSS software product itself has been retired. Almost all VSS consulting services have disappeared. Microsoft Mainstream Support is no longer available for any version of VSS. And the end is near even for Microsoft Extended Support for VSS2005. As a result, roll your own support may become more important, and the experience with VSS related by these pages may turn out to be quite useful to some despite its great age.

This material reflects experience with VSS5. The user interfaces and the feature set in VSS6 were virtually identical, so almost all of this material continued to apply for several years. But I never had any detailed knowledge of the user interfaces or feature set of VSS2005, and so simply assumed most parts of this material still applied.

These are suggestions for how to do automated unattended VSS maintenance, including backup, defrag, and ANALYZE. A specific script that implements these suggestions is available as a concrete example.

These suggestions have been divided into several categories:

Making the VSS Database Accessible

Create a "share" specifically for VSS, one folder level higher than the ...\data sub-folder so SRCSAFE.INI is included. This share should be the only possible way for network users to access the VSS Database. Do not share the whole drive the VSS Database is on (unless the VSS Database is the only thing on the drive).

Taking VSS Offline

VSS does not provide any command line interface to any of the functionality provided by SSADMIN.EXE. In particular there's no command line interface to lock the VSS Database. Fortunately it's easy to lock the VSS Database even without an interface to this functionality in VSS itself. Here's a way to programmatically force all users off VSS so maintenance such as backups can be run.

      REM This assumes the system is used only for VSS. 
      REM The NET SEND and NET SESSION commands
      REM affect _all_ remote users of this system, 
      REM not just the ones using the VSS fileshare.
      REM
      REM Also this assumes the system has an added utility named SLEEP.  
      REM For sources of such a utility, 
      REM see NT Resource Kit, MKS Toolkit, etc. 
      REM
      REM With just a little effort you should be able to do much better 
      REM than this example, which just shows that such things are in fact
      REM possible and aren't terribly difficult.
      REM
      cd  D:\VSS_MAIN\DATA\LOGGEDIN
      copy  nul  ADMIN.LCK
      net  send  /USERS  "VSS Database Going Down In 5 Minutes - SIGNOFF NOW!"
      sleep 300
      REM if share permissions are other than simply "everyone",
      REM use PERMCOPY.EXE (in NT resource kit) to save old permissions here
      net  share  VSS_MAIN  /DELETE /Y
      REM on the line above, the "hidden" /Y option "forces" the 
      REM  batch/unattended operation as though the user had answered "yes"
      net  session  /DELETE
      sleep  30
      erase  *.LOG  >nul  2>&1
      ... do maintenance ...
      cd  D:\VSS_MAIN\DATA\LOGGEDIN
      erase  ADMIN.LCK
      net  share  VSS_MAIN=D:\VSS_MAIN
      REM if share permissions should be other than simply "everyone",
      REM use PERMCOPY.EXE (in NT resource kit) to restore saved permissions here

Instead of doing erase *.LOG >nul 2>&1 you could do ss Dir -R- -yadmin,adminpass $/ >nul 2>&1. Any time user admin logs on to VSS for any reason, VSS goes through the list of users who seem to be logged in and deletes all the "phantoms" who aren't actually active. This method has the advantage of ensuring any internal VSS information is in synch with the contents of the ...\loggedin folder, but the disadvantage of possibly requiring the VSS administrative password to be present in cleartext in a readable script file.

Because forcing VSS clients off of VSS is so drastic, have your backup script send out a really nasty-looking message to all users of the "share" several minutes before you force them off. If the users are actually inactive, no harm will be done. And if a user is active, it's prudent to give him a few minutes to finish up and detach cleanly.

For folks who have inadvertently left a VSS client running, removing the share like this is totally safe. Although the OS may report that some files are being held open by the VSS client software, these files are not being written and it's not dangerous to force inactive VSS clients off. There's no need to reboot the VSS server either before or after removing the share. In fact there's no need to take resources other than the VSS Database offline.

For All VSS Maintenance Operations

Run all VSS maintenance operations from the console of the VSS server --not over the network. And be sure to access the VSS Database as local files (typically the path will include a drive letter), not through the loopback network interface (as would happen if the path were a UNC name). Do this by specifying local paths on the command line, by setting the SSDIR environment variable to a local path, by creating a separate registry entry, or even by creating a separate SRCSAFE.INI file. If VSS maintenance operations are done over a network, they will be extremely slow and as a matter of practicality will never complete, and they will be quite unreliable. If VSS maintenance operations are done through the network loopback interface, they will be slow and mildly unreliable.

You may need to separately tell each of the VSS GUI, ANALYZE, and the VSS Command Line to access the VSS Database as local files. The VSS GUI can use File|OpenSourceSafeDatabase... to access the VSS Database as a local file, then save the path as a registry entry for future use. Specify all command line parameters with local paths when invoking ANALYZE. And set a local path in the SSDIR environment variable for the SS (VSS Command Line) tools. For example, to generate a list of all files in the VSS Database with the space used by each in a reasonable amount of time, SET SSDIR=D:\VSS_MAIN before running ss Properties -R $/.

Many maintenance operations require VSS to be completely quiet. For example a backup must be run when the VSS Database is offline, and all files must be backed up. If the database changes at all during the backup, or if any file can't be backed up --perhaps because of a "sharing violation"-- the entire backup may be unusable. Because restoring VSS Databases is frequently all-or-none (there's often no way to restore just a few files), having an incomplete or inconsistent backup is a serious matter that should be avoided. Likewise the ANALYZE utility will not operate in any read-write mode and so will not attempt to "fix" anything if any VSS user appears to be logged in. So to set up unattended VSS maintenance operations you will have to have a way to force users off.

Making a Backup

Make a backup of the whole VSS Database using regular OS tools and operations first before you do anything else, so just in case something goes wrong during one of the other steps you can put the database back like it was. The backup will be very large --perhaps even larger than the VSS Database-- so it will probably need to be made to tape. Although the backup operation may run significantly faster after defragging the disk, always do the backup first. Rely on yesterday's defrag; don't try to take advantage of today's.

Backup everything under ...\data, including the RIGHTS.DAT, NAMES.DAT, and STATUS.DAT files. If possible make a backup every night. You may also choose to back up the ...\users folder once a week or so.

Sometimes it's possible to use the VSS utility SSARC to backup part of a VSS Database. Being able to backup and restore parts of the VSS Database rather than the whole thing seems like a big win. However SSARC backups may not correctly preserve either checked-out status or "project rights". Microsoft recommends against using SSARC as the primary backup tool, probably for these reasons.

Defragmenting the Disk

After a period of operation, most VSS databases become fairly badly fragmented. Running a normal defragmentation utility over the VSS database disk will significantly speed up the backup operation and may also speed up some user operations. (Because almost all defragmentation utilities do not understand VSS' "hash" scheme and largely undo it, defragging the VSS database disk can sometimes actually make some VSS operations --such as startup-- noticeably slower.)

The first time you defragment the VSS database disk, it's possible not much will happen if you haven't run ANALYZE recently. But don't be tempted to run ANALYZE before defragmenting. Stick to the order of backup first and ANALYZE last; run it again tomorrow so the next defrag will use the results of the previous ANALYZE.

Running ANALYZE

The maintenance tool that comes with VSS is called ANALYZE. Be sure to run it regularly. It recovers the space that was used by purged items (which is in limbo in a sort of second trash can until you run ANALYZE -D). It checks the entire VSS Database for possible file corruption and for inconsistency. It fixes many of the problems it discovers. If it can't fix a problem, it can be instructed to completely remove the offending file so no user will accidentally try to use it. Because this particular operation is so risky, ANALYZE actually moves each offending file to another location outside the VSS Database rather than just entirely deleting it.

As with all VSS maintenance operations, be sure to run ANALYZE from the console of the VSS server, and use drive letters (not UNC names) in all paths. ANALYZE will cheerfully go ahead and run either from another machine or through the network loopback interface (which happens if you use a UNC name), without even giving you a warning message. But don't do it. ANALYZE will run slower (maybe a lot slower). And it will run unreliably. If one of the almost inevitable network transients happens to hit ANALYZE at the wrong time, it can cause ANALYZE to spuriously report a problem or it can prevent ANALYZE from correctly fixing a real problem. If the network is flaky enough, running ANALYZE over the network may actually make the VSS database worse, causing corruption rather than preventing it. In fact it appears that running ANALYZE from another machine is the number one cause of the VSS plague of file corruption. (The number two cause of VSS file corruption is running ANALYZE while some VSS files are still accessible to users. Although file corruption is common because procedural errors are so easy, corruption is not inherent to VSS.) When you run ANALYZE from the console without using UNC names, your network can glitch like crazy yet it won't affect ANALYZE at all. And if by some chance something does go wrong, it will probably crash the whole machine immediately, which means the disks will become inaccessible before ANALYZE has a chance to piddle on your data.

ANALYZE can run for a very long time, especially during phases 1 and 2. (Phases 3 and 4 go much faster.) If the disk is badly fragmented, the VSS Database is large, and ANALYZE hasn't been run recently, it may take a whole shift to complete! Allow enough time for ANALYZE to run to completion. Do not attempt to cancel the ANALYZE operation before it's done.

Run ANALYZE as the last step of your VSS maintenance, so it can detect and possibly fix any problems that were introduced by any other maintenance step.

List all the command line switches available with ANALYZE, and figure out which ones you need to use. For example you'll want to set the "interactive" switch apppropriately for your use (-I or -I-). ANALYZE with no switches defaults to "safe" operation, which is probably not what you want.

ANALYZE can be run either on an entire VSS Database or on a list of specific files that was generated earlier, perhaps by running ANALYZE while VSS was still online. If you run ANALYZE in read-only mode to scan the database for possible errors while users are active, ANALYZE may report some spurious errors. Although you can run ANALYZE this way to generate a list of files to be checked more thoroughly and possibly fixed later, do not expect a completely clean ANALYZE run with level 4 messages even if there is nothing really wrong with any file in your database.

If some users somehow circumvent the interlocks and are actually doing something in VSS while ANALYZE is running in any read-write mode, the whole VSS Database may become unusable.


Location: (N) 42.680943, (W) -70.839384
 (North America> USA> Massachusetts> Boston> Metro North> Ipswich)

Email comments to Chuck Kollars
Time: UTC-5 (USA Eastern Time Zone)
 (UTC-4 summertime --"daylight savings time")

Peruse Chuck Kollars' Facebook Profile
All content on this Personal Website (including text, photographs, audio files, and any other original works), unless otherwise noted on individual webpages, are available to anyone for re-use (reproduction, modification, derivation, distribution, etc.) for any non-commercial purpose under a Creative Commons License.