Synchronizing the VLDB and Volume Headers

Synchronizing the VLDB and Volume Headers
	Chapter 5. Managing Volumes

AFS can provide transparent file access because the Volume Location Database (VLDB) constantly tracks volume locations. When the Cache Manager needs a file, it contacts the Volume Location (VL) Server, which reads the VLDB for the current location of the volume containing the file. Therefore, the VLDB must accurately reflect the state of volumes on the file server machines at all times. The Volume Server and VL Server automatically update a volume's VLDB entry when its status changes during a vos operation, by performing the following series of steps.

The VL Server locks the VLDB entry. The lock advises other operations not to manipulate any of the volume versions (read/write, read-only, or backup), which prevents the inconsistency that can result from multiple simultaneous operations.
The VL Server sets an intention flag in the VLDB entry that indicates the kind of operation to be performed. This flag never appears in VLDB listings because it is for internal use only. In case the operation terminates prematurely, this flag tells the Salvager which operation was interrupted. (The Salvager then determines the steps necessary either to complete the operation or return the volume to a previous consistent state. For more information on salvaging, see Salvaging Volumes.)
The Volume Server manipulates the volume. It usually sets the Off-line flag in the volume header, which makes the volume inaccessible to the File Server and other Volume Server operations during the manipulation. When the operation completes, the volume is again marked On-line.
The VL Server records any changes resulting from the operation in the VLDB entry. Once the operation is complete, it removes the intention flag set in Step 2and releases the lock set in Step 1.

If a vos operation fails while the Volume Server is manipulating the volume (corresponding to Step 3), the volume can be left in an intermediate state, which is termed corruption. In this case, the Off-line or Off-line**needs salvage** marker usually appears at the end of the first line of output from the vos examine command. To repair the corruption, run the Salvager before attempting to resynchronize the VLDB and volume headers. For salvaging instructions, see Salvaging Volumes.

More commonly, an interruption while flags are being set or removed (corresponding to Step 1, Step 2, or Step 4) causes a discrepancy between the VLDB and volume headers. To resynchronize the VLDB and volumes, use the vos syncvldb and vos syncserv commands. To achieve complete VLDB consistency, it is best to run the vos syncvldb command on all file server machines in the cell, and then run the vos syncserv command on all file server machines in the cell.

There are several symptoms that indicate a volume operation failed:

Error messages on the standard error stream or in server process log files indicate that an operation terminated abnormally. Perhaps you had to halt the operation before it completed (for instance, by using a signal such as Ctrl-c), or a file server machine or server process was not functioning when the operation ran. To determine if a machine or process is still not functioning, issue the bos status command as described in Displaying Process Status and Information from the BosConfig File.
A subsequent vos operation fails because a previous failure left a VLDB entry locked. Sometimes an error message reports that a volume is locked. To display a list of locked volumes, use the -locked flag on the vos listvldb command as described in Displaying VLDB Entries.
If the only problem with a volume is that its VLDB entry is locked, you probably do not need to synchronize the entire VLDB. Instead use the vos unlock or vos unlockvldb command to unlock the entry, as described in Unlocking and Locking VLDB Entries.
A subsequent vos operation fails because a previous failure left a volume marked as offline. To check a volume's current status, check the first line of output from the vos examine command as described in Displaying One Volume's VLDB Entry and Volume Header.

The vos syncvldb command corrects the information in the Volume Location Database (VLDB) either about all volumes housed on a file server machine, about the volumes on just one partition, or about a single volume. If checking about one or more partitions, the command contacts the Volume Server to obtain a list of the volumes that actually reside on each partition. It then obtains the VLDB entry for each volume from the VL Server. It changes the VLDB entry as necessary to reflect the state of the volume on the partition. For example, it creates or updates a VLDB entry when it finds a volume for which the VLDB entry is missing or incomplete. However, if there is already a VLDB entry that defines a different location for the volume, or there are irreconcilable conflicts with other VLDB entries, it instead writes a message about the conflict to the standard error stream. The command never removes volumes from the file server machine.

When checking a single volume's VLDB entry, the command also automatically performs the operations invoked by the vos syncserv command: it not only verifies that the VLDB entry is correct for the specified volume type (read/write, backup, or read-only), but also checks that any related volume types mentioned in the VLDB entry actually exist at the site listed in the entry.

The vos syncserv command verifies that each volume type (read/write, read-only, and backup) mentioned in a VLDB entry actually exists at the site indicated in the entry. It checks all VLDB entries that mention a site either on any of a file server machine's partitions or on one partition. Note that command can end up inspecting sites other than on the specified machine or partition, if there are read-only versions of the volume at sites other than the read/write site.

The command alters any incorrect information in the VLDB, unless there is an irreconcilable conflict with other VLDB entries. In that case, it writes a message to the standard error stream instead. The command never removes volumes from their sites.

To synchronize the VLDB with volume headers

Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.
```
   % bos listusers <machine name>
```
Issue the vos syncvldb command to make the VLDB reflect the true state of all volumes on a machine or partition, or the state of one volume.
Note
To synchronize the VLDB completely, issue the command repeatedly, substituting each file server machine in your cell for the -server argument in turn and omitting the -partition and -volume arguments, before proceeding to Step 3.
```
   % vos syncvldb -server <machine name> [-partition <partition name>] \
        [-volume <volume name or ID>] [-verbose >> file]
```
where
syncv
Is the shortest acceptable abbreviation of syncvldb.
-server
Names the file server machine housing the volumes for which to verify VLDB entries. If you are also providing the -volume argument, this argument must name the machine where the volume actually resides.
-partition
Identifies the partition (on the file server machine specified by the -server argument) housing the volumes for which to verify VLDB entries. In general, it is best to omit this argument so that either the VLDB entries for all volumes on a server machine are corrected (if you do not provide the -volume argument), or so that you do not need to guarantee that the partition actually houses the volume named by the -volume argument.
-volume
Specifies the name or volume ID number of a single volume for which to verify the VLDB entry.
-verbose >> file
Directs a detailed trace to the file called file, which can be either in AFS or on the local disk of the machine on which you are issuing the command. The command often writes a large amount of output to the standard output stream; writing it to a file enables you to examine the output more carefully.
Issue the vos syncserv command to inspect each volume for which the VLDB lists a version at the specified site.
Note
To synchronize the VLDB completely, issue the command repeatedly, substituting each file server machine in your cell for the machine name argument in turn and omitting the partition name argument.
```
   % vos syncserv <machine name> [<partition name>] [-v >> file]
```
where
syncs
Is the shortest acceptable abbreviation of syncserv.
machine name
Names the file server machine mentioned in each VLDB entry to check.
partition name
Identifies the partition mentioned in each VLDB entry to check. If synchronizing the entire VLDB, omit this argument.
-v >> file
Directs a detailed trace to the file called file, which can be either in AFS or on the local disk of the machine on which you are issuing the command. The command often writes a large amount of output to the standard output stream; writing it to a file enables you to examine the output more carefully.