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