backup volsetrestore - Restores all volumes in a volume set

backup volsetrestore << [-name <volume set name] >>> << [-file <file name] >>> << [-portoffset <TC port offset+] >>> << [-extension <new volume name extension] >>> [-n] [-localauth] << [-cell <cell name] >>> [-help]

backup vols << [-na <volume set name] >>> << [-f <file name] >>> << [-p <TC port offset+] >>> << [-e <new volume name extension] >>> [-n] [-l] << [-c <cell name] >>> [-h]

The backup volsetrestore command restores the complete contents of a group of read/write volumes to the file system, by restoring data from the last full dump and all subsequent incremental dumps of each volume. It is most useful for recovering from loss of data on multiple partitions, since it can restore each of a defined set of volumes to a different site.

(If the CWFILE YES instruction appears in the /var/lib/openafs/backup/CFG_device_name file associated with the specified port offset, then the backup volsetrestore command restores data from the backup data file listed for that port offset in the Tape Coordinator's /var/lib/openafs/backup/tapeconfig file, instead of from tape. For the sake of clarity, the following text refers to tapes only, but the Backup System handles backup data files in much the same way.)

If restoring one or more volumes to a single site only, it is usually more efficient to use the backup volrestore command. If restoring all volumes that resided on a single partition, it is usually more efficient to use the backup diskrestore command.

Indicate the volumes to restore by providing either the -name argument or the -file argument: The -name argument names a volume set. The Backup System restores all volumes listed in the Volume Location Database (VLDB) that match the server, partition, and volume name criteria defined in the volume set's volume entries, and for which dumps are available. It restores the volumes to their current site (machine and partition), and by default overwrites the existing volume contents. It is not required that the volume set was previously used to back up volumes (was used as the -volumeset option to the backup dump command). It can be defined especially to match the volumes that need to be restored with this command, and that is usually the better choice. Indeed, a temporary volume set, created by including the -temporary flag to the backup addvolset command, can be especially useful in this context. A temporary volume set is not added to the Backup Database and exists only during the current interactive backup session, which is suitable if the volume set is needed only to complete the single restore operation initialized by this command. The reason that a specially defined volume set is probably better is that volume sets previously defined for use in dump operations usually match the backup version of volumes, whereas for a restore operation it is best to define volume entries that match the base (read/write) name. In that case, the Backup System searches the Backup Database for the newest dump set that includes either the read/write or the backup version of the volume. If, in contrast, a volume entry explicitly matches the volume's backup or read-only version, the Backup System restores dumps of that volume version only. The -file argument names a file that lists specific volumes and the site to which to restore each. The volume name must match the name used in Backup Database dump records rather than in the VLDB, if they differ, because the Backup System does not look up volumes in the VLDB. The specified site can be different than the volume's current one; in that case, the Backup System removes the current version of the volume and updates the volume's location information in the VLDB.

If all of the full and incremental dumps of all relevant volumes were not written to a type of tape that a single Tape Coordinator can read, use the -portoffset argument to list multiple port offset numbers in the order in which the tapes are needed (first list the port offset for the full dump, second the port offset for the level 1 incremental dump, and so on). This implies that the full dumps of all relevant volumes must have been written to a type of tape that the first Tape Coordinator can read, the level 1 incremental dumps to a type of tape the second Tape Coordinator can read, and so on. If dumps are on multiple incompatible tape types, use the backup volrestore command to restore individual volumes, or use this command after defining new volume sets that group together volumes that were dumped to compatible tape types. For further discussion, see the IBM AFS Administration Guide.

By default, the Backup System overwrites the contents of an existing volume with the restored data. To create a new volume to house the restored version instead, use the -extension argument. The Backup System derives the new volume's name by adding the specified extension to the read/write base name, and creates a new VLDB entry. The command does not affect the existing volume in any way. However, if a volume with the specified extension also already exists, the command overwrites it.

The -n flag produces a list of the volumes to be restored if the -n flag were not included, without actually restoring any volumes. See the OUTPUT manpage for a detailed description of the output, and suggestions on how to combine it most effectively with the -file and -name arguments.

The execution time for a backup volsetrestore command depends on the number of volumes to be restored and the amount of data in them, but it can take hours to restore a large number of volumes. One way to reduce the time is to run multiple instances of the command simultaneously, either using the -name argument to specify disjoint volume sets for each command, or the -file argument to name files that list different volumes. This is possible if there are multiple available Tape Coordinators that can read the required tapes. Depending on how the volumes to be restored were dumped to tape, specifying disjoint volume sets can also reduce the number of tape changes required.

The Tape Coordinator's default response to this command is to access the first tape it needs by invoking the CWMOUNT instruction in the local /var/lib/openafs/backup/CFG_device_name file, or by prompting the backup operator to insert the tape if there is no CWMOUNT instruction. However, if the CWAUTOQUERY NO instruction appears in the CFG_device_name file, or if the issuer of the butc command included the -noautoquery flag, the Tape Coordinator instead expects the tape to be in the device already. If it is not, or is the wrong tape, the Tape Coordinator invokes the CWMOUNT instruction or prompts the operator. It also invokes the CWMOUNT instruction or prompts for any additional tapes needed to complete the restore operation; the backup operator must arrange to provide them.

Names a volume set to restore. The Backup System restores all of the volumes listed in the VLDB that match the volume set's volume entries. Provide this argument or the -file argument, but not both. Specifies the full pathname of a file that lists one or more volumes and the site (file server machine and partition) to which to restore each. Use either this argument or the -name argument, but not both. Each volume's entry must appear on its own (unbroken) line in the file, and have the following format:

    <machine> <partition> <volume> [<comments> ...]

If the -n flag is not provided, the command displays a unique task ID number for the operation, in two places: In the shell window, directly following the command line. In the Tape Coordinator window, if the butc process was started at debug level 1.

The task ID number is not the same as the job ID number displayed by the backup jobs command when the backup volsetrestore command is issued in interactive mode. The Backup System does not assign either type of ID number until the restoration process actually begins.

When the -n flag is included, no task ID or job ID numbers are reported because none are assigned. Instead, the output begins with a count of the number of volumes to be restored, followed by a line for each dump of a volume. For each volume, the line representing the most recent full dump appears first, and lines for any subsequent incremental dumps follow, ordered by dump level. The lines for a given volume do not necessarily appear all together, however.

The format of each line is as follows (the output is shown here on two lines only for legibility reasons):

   <machine> <partition> <volume_dumped> # as <volume_restored>; \
       <tape_name> (<tape_ID>); pos <position_number>; <date>

One way to generate a file for use as input to the -file argument is to combine the -name and -n options, directing the output to a file. The IBM AFS Administration Guide section on using the Backup System to restore data explains how to edit the file as necessary before using it as input to the -file argument.

The output of this command includes only volumes for which the Backup Database includes at least one dump record. The command interpreter generates a message on the standard error stream about volumes that do not have dump records but either are listed in the file named by the -file argument, or appear in the VLDB as a match to a volume entry in the volume set named by the -name argument.

The following command restores all volumes included in entries in the volume set named CWdata.restore, which was created expressly to restore data to a pair of file server machines on which all data was corrupted due to a software error. All volumes are restored to the sites recorded in their entries in the VLDB.

   % backup volsetrestore -name data.restore
   Starting restore
   backup: task ID of restore operation: 112
   backup: Finished doing restore

   % backup volsetrestore -file /tmp/restore
   Starting restore
   backup: task ID of restore operation: 113
   backup: Finished doing restore

   fs1.abc.com b user.pat
   fs1.abc.com b user.terry
   fs1.abc.com b user.smith
   fs2.abc.com c user.jones
          .         .     .
          .         .     .

The issuer must be listed in the /etc/openafs/server/UserList file on every machine where the Backup Server or Volume Location (VL) Server is running, and on every file server machine that houses an affected volume. If the -localauth flag is included, the issuer must instead be logged on to a server machine as the local superuser CWroot.

the butc(5) manpage, the backup(8) manpage, the backup_addvolentry(8) manpage, the backup_addvolset(8) manpage, the backup_diskrestore(8) manpage, the backup_dump(8) manpage, the backup_volrestore(8) manpage, the butc(8) manpage

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

This documentation is covered by the IBM Public License Version 1.0. It was converted from HTML to POD by software written by Chas Williams and Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.