vob_snapshot

Copies the VOB databases of all local VOBs or replicas configured for database snapshot

APPLICABILITY

ClearCase (administrative command), Attache (administrative command)

SYNOPSIS

ccase-home-dir\etc\vob_snapshot

DESCRIPTION

The vob_snapshot command makes an on-disk copy of a local, locked VOB database. Using this command reduces the amount of time a VOB database needs to be locked when you back up the VOB. Later, as part of your standard system backup procedure, the VOB storage directory (minus the VOB database directory) and the VOB database snapshot can be backed up without locking the VOB. Because the database snapshot and VOB storage pool backups occur at different times, they are likely to be slightly out of sync. To correct this skew, the checkvob utility resynchronizes the VOB database and storage pools when you run vob_restore.

By default, the ClearCase scheduler runs vob_snapshot periodically. See the schedule reference page for information on describing and changing scheduled jobs. If no locally stored VOBs are configured for database snapshot, vob_snapshot exits silently.

A local VOB's database is copied only if snapshot parameters have been applied to it with the vob_snapshot_setup utility. See Per VOB (or Replica) Snapshot Parameters.

Per VOB (or Replica) Snapshot Parameters

When vob_snapshot runs on a VOB host, it checks each locally stored VOB for the existence of a multipart string attribute that specifies snapshot parameters. An administrator uses the vob_snapshot_setup utility to apply the vob_snapshot_parameters attribute to each VOB or replica for which snapshots will be taken. The attribute string's individual components specify the following:

• Where to put the VOB database snapshot

  A disk location that will store the snapshot. Typically, this location gets backed up later (along with the VOB storage directory as part of normal backup operations), and it is overwritten by the next snapshot.

• Whether to run db_check on the VOB database snapshot

  The db_check utility performs fundamental, non-ClearCase-related database consistency and integrity checks. (Later, at recover time, checkvob may examine the VOB database looking for ClearCase anomalies.) The db_check pass occurs after all snapshots are complete on the local host.

See vob_snapshot_setup for more information on setting these parameters for a particular VOB.

Database Snapshot Details

When vob_snapshot encounters a VOB that is configured for database snapshot, it performs the following steps (logging messages in the ccase-home-dir\var\log\snap_log file along the way):

1. Verifies that the snapshot target directory exists and is writable.
2. Locks the VOB. If vob_snapshot cannot lock the VOB, it proceeds with the snapshot, but logs the snapshot's status as questionable.
3. Checks the VOB's specified snapshot target directory for sufficient disk space.
4. Creates a subdirectory whose name is the VOB's replica UUID. If a directory with that name already exists, remove it first (that is, remove the previous snapshot).
5. Copies the VOB database directory tree (using xcopy) to the subdirectory created in Step #3.
6. Unlocks the VOB.
7. Repeats Step #1 through Step #6 for the next VOB.
8. Runs db_check on all VOBs configured for this check.

   NOTE: If the log reveals a failed db_check, check the log for obvious errors. If you cannot resolve the problem, contact Rational Technical Support.

If You Do Not Use vob_snapshot

You must lock the VOB and back up the entire VOB storage directory. Such a backup avoids the issue of skew between VOB database snapshot and VOB storage pools (which are typically backed up some time after the snapshot), but it requires that the VOB remain locked during the entire backup operation.

PERMISSIONS AND LOCKS

Permissions Checking: You must have the appropriate permissions to lock the VOB. See the permissions reference page.

Locks: The VOB must be locked to guarantee the integrity of a database snapshot. If vob_snapshot cannot lock the VOB (because it is run with insufficient permissions, or another user locked the VOB), it proceeds with the copy operation but logs the snapshot's status as "questionable." This status is upgraded to "successful" if the optional post-snapshot db_check pass succeeds.

OPTIONS AND ARGUMENTS

None.

EXAMPLE VOB BACKUP AND RECOVER SCENARIO USING vob_snapshot

This sample backup/recover scenario uses the utilities vob_snapshot_setup, vob_snapshot, and vob_restore.

1. Log in to the VOB host.
2. Configure the VOB \vob_src for daily database snapshots:

"c:\Program Files\Rational\ClearCase\etc\vob_snapshot_setup" modparam ^
-dbcheck yes -snap_to \\saturn\bigdisk\snaps\vob_src  \vob_src

The VOB database is copied to a subdirectory of the -snap_to directory you specify. The subdirectory name matches the VOB's replica UUID (which you can display with vob_snapshot_setup lsvob -long). In this example, the snapshot is stored in ...\snaps\vob_src\replica-uuid.

NOTE: If run without command line options, vob_snapshot_setup modparam prompts for all necessary input and displays explanatory text.

1. Confirm that \vob_src is in the local host's snapshot list:

"c:\Program Files\Rational\ClearCase\etc\vob_snapshot_setup" lsvob

\vob_src
...

1. Make sure the -snap_to directory \\saturn\bigdisk\snaps\vob_src and the VOB storage directory are saved by your normal backup routine.

   NOTE: Although \vob_src must be locked at database snapshot time, it need not be locked when your normal backup routine saves the snapshot and VOB storage directory.

2. Let VOB \vob_src be locked and its database copied to disk by the standard vob_snapshot job run by the ClearCase scheduler. Also, let your backup procedure capture the VOB storage directory and VOB database snapshot.

   A common routine is to run vob_snapshot early in the morning or at lunch time, when the VOB lock is least likely to interfere with nightly builds, and to back up VOB storage directories at night.

(End backup scenario)

1. \vob_src fails (corrupt or lost database, corrupt or lost storage pools, and so on).

(Begin recover scenario)

1. Log in to the VOB host as a user with permission to lock the VOB and stop and start ClearCase.
2. As a precaution, lock the VOB, so that no further changes can be made. Note that read access can continue if the VOB is in a readable state (damaged database only, for example).

cmd-context lock -c "vob recover required" vob:\vob_src

1. Retrieve the most recent VOB database snapshot and storage directory from backup media.
   1. Retrieve the most recent VOB database snapshot directory, \\saturn\bigdisk\snaps\vob_src.

   NOTE: The most recent snapshot may still be on disk, or it may be on backup media.

   1. Use lsvob \vob_src to identify the storage directory pathname:

      cmd-context lsvob \vob_src

      \vob_src       \\io\vobstore\vob_src.vbs

   2. Retrieve the VOB storage directory from backup media, and place it in temporary storage location \\io\vobstore\temp.vbs. (If no users are reading the damaged VOB, and it is presumed destroyed, you may choose to restore the VOB storage backup directly to its registered location, rather than to a temporary area.)
2. Run vob_restore to merge the VOB database and storage directory:

"c:\Program Files\Rational\ClearCase\etc\vob_restore"   \vob_src

NOTE: If run without command line options, vob_restore prompts for all necessary input and displays explanatory text.

vob_restore does the following:

• Moves the snapshot directory to a temporary storage location, overwriting the VOB database that was (most likely) restored from the VOB storage directory backup
• Unregisters \vob_src from the local host's network region
• Stops ClearCase on the local host
• Prompts you to move or remove the VOB storage at the original storage location, if it exists
• Copies the restored VOB storage directory from its temporary storage location to the VOB's registered location
• (Optional) Runs checkvob to find and fix inconsistencies between the data containers in VOB storage pools and the VOB database

1. Restart ClearCase on the local host.
2. Re-register \vob_src:

cmd-context mktag -vob -tag \vob_src \\io\vobstore\vob_src.vbs

cmd-context register -vob \\io\vobstore\vob_src.vbs

End recover scenario 

See also vob_snapshot_setup and vob_restore.

THE SNAPSHOT LOG

vob_snapshot's operation is recorded in the log file ccase-home-dir\var\log\snap_log. Here are some common error and status messages from snap_log:

Successful snapshot messages:

NOTE: VobTag: \vob_src
NOTE: Replica UUID: 0b9ccb24.8dc211cf.af59.00:01:80:73:db:6f
NOTE: Family UUID: 0b9ccb20.8dc211cf.af59.00:01:80:73:db:6f
NOTE: Dbcheck succeeded
NOTE: SNAPSHOT COMPLETED SUCCESSFULLY

The following messages may be generated when vob_snapshot runs on an unlocked VOB. If the database check passes, the snapshot is upgraded from "questionable" to "successful." You should always lock a VOB before copying its VOB database with vob_snapshot.

ERROR: Could not lock the replica for the copy. Copied anyway.
ERROR: The snap was done without the vob lock in place.

ERROR: SNAPSHOT QUESTIONABLE
NOTE : The snap was done unlocked but the database checked ok

The following error occurs if the user account under which vob_snapshot executes does not have permission to overwrite the directory supplied as a -snap_to argument to vob_snapshot_setup:

ERROR: The snap_to directory for vob \vob_src is not writable

EXAMPLES

• List all VOBs on the local host's snapshot list (VOBs to which snapshot parameters have been applied with vob_snapshot_setup modparam). Then, take VOB database snapshots for all VOBs in the list.

cd "c:\Program Files\Rational\ClearCase\etc"

vob_snapshot_setup lsvob

\vob_src
\vob_lib

vob_snapshot

• Add local VOB \vob_prj to the current host's snapshot list. Then, take VOB database snapshots for all VOBs in the list.

cd "c:\Program Files\Rational\ClearCase\etc"

vob_snapshot_setup modparam -dbcheck yes -snap_to \\saturn\bigdisk\snaps\proj1  \vob_prj1

vob_snapshot

FILES

ccase-home-dir\var\log\snap_log

WINDOWS NT REGISTRY KEYS

HKEY_LOCAL_MACHINE\SOFTWARE\Atria\ClearCase\CurrentVersion\snapshot

SEE ALSO

checkvob, schedule, vob_restore, vob_snapshot_setup