Section: AFS Command Reference (8)
Updated: OpenAFS


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 agroup of read/write volumes to the file system, by restoring data from thelast full dump and all subsequent incremental dumps of each volume. It ismost useful for recovering from loss of data on multiple partitions, sinceit can restore each of a defined set of volumes to a different site.

(If the FILE YES instruction appears in the/usr/afs/backup/CFG_device_name file associated with the specifiedport offset, then the backup volsetrestore command restores data fromthe backup data file listed for that port offset in the Tape Coordinator's/usr/afs/backup/tapeconfig file, instead of from tape. For the sake ofclarity, the following text refers to tapes only, but the Backup Systemhandles backup data files in much the same way.)

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

Indicate the volumes to restore by providing either the -name argumentor the -file argument:

The -name argument names a volume set. The Backup System restores allvolumes listed in the Volume Location Database (VLDB) that match theserver, partition, and volume name criteria defined in the volume set'svolume entries, and for which dumps are available. It restores the volumesto their current site (machine and partition), and by default overwritesthe existing volume contents.

It is not required that the volume set was previously used to back upvolumes (was used as the -volumeset option to the backup dumpcommand). It can be defined especially to match the volumes that need tobe restored with this command, and that is usually the betterchoice. Indeed, a temporary volume set, created by including the-temporary flag to the backup addvolset command, can be especiallyuseful in this context. A temporary volume set is not added to the BackupDatabase and exists only during the current interactive backup session,which is suitable if the volume set is needed only to complete the singlerestore operation initialized by this command.

The reason that a specially defined volume set is probably better is thatvolume sets previously defined for use in dump operations usually matchthe backup version of volumes, whereas for a restore operation it is bestto define volume entries that match the base (read/write) name. In thatcase, the Backup System searches the Backup Database for the newest dumpset that includes either the read/write or the backup version of thevolume. If, in contrast, a volume entry explicitly matches the volume'sbackup or read-only version, the Backup System restores dumps of thatvolume version only.

The -file argument names a file that lists specific volumes and thesite to which to restore each. The volume name must match the name used inBackup Database dump records rather than in the VLDB, if they differ,because the Backup System does not look up volumes in the VLDB. Thespecified site can be different than the volume's current one; in thatcase, the Backup System removes the current version of the volume andupdates the volume's location information in the VLDB.

If all of the full and incremental dumps of all relevant volumes were notwritten to a type of tape that a single Tape Coordinator can read, use the-portoffset argument to list multiple port offset numbers in the orderin which the tapes are needed (first list the port offset for the fulldump, second the port offset for the level 1 incremental dump, and soon). This implies that the full dumps of all relevant volumes must havebeen 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 TapeCoordinator can read, and so on. If dumps are on multiple incompatibletape types, use the backup volrestore command to restore individualvolumes, or use this command after defining new volume sets that grouptogether volumes that were dumped to compatible tape types. For furtherdiscussion, see the IBM AFS Administration Guide.

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

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

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

The Tape Coordinator's default response to this command is to access thefirst tape it needs by invoking the MOUNT instruction in the local/usr/afs/backup/CFG_device_name file, or by prompting the backupoperator to insert the tape if there is no MOUNT instruction. However,if the AUTOQUERY NO instruction appears in the CFG_device_namefile, or if the issuer of the butc command included the -noautoqueryflag, the Tape Coordinator instead expects the tape to be in the devicealready. If it is not, or is the wrong tape, the Tape Coordinator invokesthe MOUNT instruction or prompts the operator. It also invokes theMOUNT instruction or prompts for any additional tapes needed tocomplete the restore operation; the backup operator must arrange toprovide them. 


-name <volume set name>
Names a volume set to restore. The Backup System restores all of thevolumes listed in the VLDB that match the volume set's volumeentries. Provide this argument or the -file argument, but not both.
-file <file name>
Specifies the full pathname of a file that lists one or more volumes andthe 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> ...]
Names the file server machine to which to restore the volume.
Names the partition to which to restore the volume.
Names the volume to restore. It is generally best to specify the base(read/write) name of each volume. In this case, the Backup System searchesthe Backup Database for the newest dump set that includes a dump of eitherthe read/write or the backup version of the volume. It restores the dumpsof that version of the volume, starting with the most recent fulldump. If, in contrast, the name explicitly includes the .backup or.readonly extension, the Backup System restores dumps of that volumeversion only.
<comments> ...
Is any other text. The Backup System ignores any text on each line thatappears after the volume name, so this field can be used for notes helpfulto the backup operator or other administrator.

Do not use wildcards (for example, .*) in the <machine>, <partition>,or <volume> fields. It is acceptable for multiple lines in the file toname the same volume, but the Backup System processes only the first ofthem.

-extension <new volume name extension>
Creates a new volume for each volume specified by the -name or -fileargument, to house the restored data from that volume. The Backup Systemderives the new volume's name by appending the specified string to theread/write base name, and creates a new VLDB volume entry. It preservesthe contents of each existing volume. Any string other than .readonlyor .backup is acceptable, but the combination of the base name andextension cannot exceed 22 characters in length. To use a period toseparate the extension from the name, specify it as the first character ofthe string (as in .rst, for example).
-portoffset <TC port offset>+
Specifies one or more port offset numbers (up to a maximum of 128), eachcorresponding to a Tape Coordinator to use in the operation. If there ismore than one value, the Backup System uses the first one when restoringthe full dump of each volume, the second one when restoring the level 1incremental dump of each volume, and so on. It uses the final value in thelist when restoring dumps at the corresponding depth in the dump hierarchyand all dumps at lower levels.

Provide this argument unless the default value of 0 (zero) is appropriatefor all dumps. If 0 is just one of the values in the list, provide itexplicitly in the appropriate order.

Displays a list of the volumes to be restored if the flag were notincluded, without actually restoring them. the OUTPUT manpage details the format ofthe output. When combined with the -name argument, its output is easilyedited for use as input to the -file argument on a subsequent backupvolsetrestore command.
Constructs a server ticket using a key from the local/usr/afs/etc/KeyFile file. The backup command interpreter presentsit to the Backup Server, Volume Server and VL Server during mutualauthentication. Do not combine this flag with the -cell argument. Formore details, see the backup(8) manpage.
-cell <cell name>
Names the cell in which to run the command. Do not combine this argumentwith the -localauth flag. For more details, see the backup(8) manpage.
Prints the online help for this command. All other valid options areignored.


If the -n flag is not provided, the command displays a unique task IDnumber 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 debuglevel 1.

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

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

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

   <machine> <partition> <volume_dumped> # as <volume_restored>; \       <tape_name> (<tape_ID>); pos <position_number>; <date>
Names the file server machine that currently houses the volume, as listedin the VLDB.
Names the partition that currently houses the volume, as listed in theVLDB.
Specifies the version (read/write or backup) of the volume that wasdumped, as listed in the Backup Database.
Specifies the name under which to restore the volume. The Backup Systemonly restores data to read/write volumes. If the -extension argument isincluded, then the specified extension appears on the name in this field(for example, user.pat.rst).
Names the tape containing the dump of the volume, from the BackupDatabase. If the tape has a permanent name, it appears here; otherwise, itis the AFS tape name.
The tape ID of the tape containing the dump of the volume, from the BackupDatabase.
Specifies the dump's position on the tape (for example, 31 indicatesthat 30 volume dumps precede the current one on the tape). If the dump waswritten to a backup data file, this number is the ordinal of the 16KB-offset at which the volume's data begins.
The date and time when the volume was dumped.

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

The output of this command includes only volumes for which the BackupDatabase includes at least one dump record. The command interpretergenerates a message on the standard error stream about volumes that do nothave dump records but either are listed in the file named by the -fileargument, or appear in the VLDB as a match to a volume entry in the volumeset named by the -name argument. 


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

   % backup volsetrestore -name data.restore   Starting restore   backup: task ID of restore operation: 112   backup: Finished doing restore
The following command restores all volumes that have entries in the filenamed /tmp/restore:

   % backup volsetrestore -file /tmp/restore   Starting restore   backup: task ID of restore operation: 113   backup: Finished doing restore
The /tmp/restore file has the following contents: b user.pat b user.terry b user.smith c user.jones          .         .     .          .         .     .


The issuer must be listed in the /usr/afs/etc/UserList file on everymachine 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 aserver machine as the local superuser root. 


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. <> All Rights Reserved.

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




This document was created byman2html,using the manual pages.