Vault Verify for verifying file revisions

This topic describes how to use the Vault Verify utility to verify file revisions.

Overview

Vault Verify utility is a Java application that reports on and optionally attempts to resolve integrity issues with a StarTeam Native-II vault. It requires a StarTeam configuration name and, if the starteam-server-configs.xml file is not in the current folder, the path name of the folder containing this file. Vault Verify opens the corresponding database via JDBC, but it does not modify the database. Vault Verify also parses the hive-index.xml file to learn the location of vault hives.

This topic contains the following information:

Checks Performed by Vault Verify.
Vault Verify Requirements.
Tips and Best Practices for Using Vault Verify.

Checks Performed by Vault Verify

Vault Verify is a command line utility that performs checks for corrupt, missing, or stray files for Native-II vaults. Optionally, Vault Verify can attempt to repair archive files based on what problem it finds with each file. For example, this utility will locate stray files and move them to a specified location. The administrator may then archive them off or delete them (after verifying their results).

Corrupt Files Check

This check validates all files in archive folders. For each file found in an archive folder, Vault Verify ensures that:

The name of the file is a valid archive filename.
The file is located in the correct folder based on its name.
The file can be opened and read.
The actual MD5 for the file matches its filename.
If it is a compressed (.gz) file, its format is a valid GZIP format.

Note: If the repair option is requested, corrupt files are moved to the default or a configured corrupt files folder. Once moved, the corrupt file is classified as missing if it is referenced in the database.

Missing Files Check

This check ensures that all archive files defined in the database are present on disk. If the repair option is requested, Vault Verify will attempt to recover missing files from vault caches or other archive files.

Note: If you specify the useca (use Cache Agent) option, Vault Verify attempts to recover missing files from a remote Cache Agent.

Stray Files Check

This check ensures that all archive files in the vault are represented by corresponding database records. If the repair option is requested, stray files are moved to the default or a configurable stray files folder.

Vault Verify prerequisites

Vault Verify requires the following:

Read access to the database used by StarTeam Server.
You must download and install the Oracle JDBC driver for Oracle configurations. Go to http://www.oracle.com/technology/software/index.html, and scroll down to the Drivers section and click JDBC. Click the latest JDBC driver link. Following the download instructions, a page displays a list with JAR files. Download the JAR file which corresponds to the JDK version you are using.
Note: You must have an Oracle.com user name and password before downloading the JDBC driver. If you do not have an account, you can create one from the Login page. Save the JAR file in the VaultVerify installation folder.
Vault Verify must have read access to starteam-server-configs.xml and hive-index.xml.
Vault Verify requires read access to the archive files for each hive and write access to the folders for each hive if you use the repair option.

Tips and best practices for using vault verify

The following are tips and best practices for working with Vault Verify:

You should run Vault Verify using the tailored batch file, VaultVerify.bat (or the shell script version on Linux) to ensure that the proper version of Java is used. The batch file (or shell script) is located in the Vault Verify installation folder.
You must install the Vault Verify utility on the same system where you are running StarTeam Server. Vault Verify installs in its own Vault Verify folder under the StarTeam Server installation folder. For example, on a Windows system, Vault Verify installs in the C:\Program Files\Micro Focus\StarTeam Server <version>\Vault Verify folder.
Vault Verify must have read access to the database used by StarTeam Server. By default, it uses the same userid as the StarTeam Server to access the database. If the password to that userid is not blank, it must be explicitly passed to Vault Verify. An alternate database userid can also be passed. Note that for Oracle configurations on Linux, Vault Verify requires the Oracle JDBC driver, which must be downloaded and installed by the customer.
It is recommended that you run Vault Verify at least once per quarter and as often as once a month. It is also recommended that you run Vault Verify on a restored copy of the production database and the vault backup on a test box. Running Vault Verify on a test box not only ensures that the backup/restore procedure is working, but it offloads the I/O that Vault Verify does from the production server.
If you are running Vault Verify against a mid- to large-size database, you should pass the Java -Xmx1024m parameter to avoid running out of memory.
When using the corrupt check (this check opens and reads every archive file), Vault Verify returns results at 3 to 30 GB/hour depending on the system hardware and the size of the vault. When also using the missing and stray checks (these checks are much faster and perform file existence tests--they do not open or read files), each check adds another 5-30 minutes to the run time depending on the system hardware and the size of the vault.
The requested check options are performed in the following order: corrupt, missing, and stray. Consequently, if repair is used along with the corrupt and missing checks, a corrupt file will first be moved to the corrupt files folder and then treated as a missing file.
The specified StarTeam Server configuration can be in use when Vault Verify is running. However, the stray check and the repair option will be ignored if the StarTeam Server configuration is in use.
All reporting, including problem files, displays in the console window (if so desired, you can pipe this information to a text file). If you request the repair option, the results of any repair attempts are also displayed. The verbose option provides additional progress and diagnostic reporting. Vault Verify uses a stored procedure for reporting the share paths (project/view/folder path) of each valid archive file that is corrupt or missing. If this procedure is not present, the file name of problem files is reported, but share paths are not.
The Vault Verify utility is contained in a set of jar files. The main file is VaultVerify.jar. It requires JRE 1.5 or newer. To get help text for Vault Verify, you can enter java -jar VaultVerify.jar -help. Usage text is also available in this help system.
StarTeam Server always looks for the starteam-server-config.xml file in its own installation folder to determine whether the server is running. Be cautious about this fact if you decide to copy this file to a different location and then indicate to Vault Verify its new location with the path option. If you have indicated in the copied version of starteam-server-config.xml that the server is not running and use the stray and repair options in Vault Verify, these options are not ignored if StarTeam Server is running.
The server configuration name passed to Vault Verify is case-sensitive, and if it includes spaces, you must pass the server configuration name to Vault Verify in quotation marks.
By default, Vault Verify uses the same userid as the StarTeam Server to access the database. If the password to that userid is not blank, it must be explicitly passed to Vault Verify. An alternate database userid can also be passed.
By default, the output from Vault Verify is output to the command window. We recommend that you pipe the output to a file so that if needed, you can send the information to Technical Support.

Verifying file revisions with Vault Verify

By default, the Vault Verify utility installs into the C:\Program Files\Borland\StarTeam Server <version>\VaultVerify folder on a Windows machine.

In general, you can run Vault Verify from the command line as follows: Vault Verify [options] "server configuration" .