Section: AFS Command Reference (8)
Updated: OpenAFS


backup volrestore - Restores one or more volumes 


backup volrestore << -server <destination machine >>>
    << -partition <destination partition >>>
    << -volume <volume(s) to restore+ >>>
    << [-extension <new volume name extension] >>>
    << [-date <date from which to restore+] >>>
    << [-portoffset <TC port offsets+] >>> [-n]
    [-localauth] << [-cell <cell name] >>> [-help]

backup volr << -s <destination machine >>>
    << -pa <destination partition >>> << -v <volume(s) to restore+ >>>
    << [-e <new volume name extension] >>>
    << [-d <date from which to restore+] >>> << [-po <TC port offsets+] >>>
    [-n] [-l] << [-c <cell name] >>> [-h] 


The backup volrestore command restores the contents of one or morevolumes to the site indicated by the -server and -partitionarguments. Use the command either to overwrite the contents of existingvolumes with the restored data or to create new volumes while retainingthe existing ones. The specified site does not have to be the current sitefor the volumes.

(If the FILE YES instruction appears in the/usr/afs/backup/CFG_device_name file associated with the specifiedport offset, then the backup volrestore command restores data from thebackup data file listed for that port offset in the Tape Coordinator's/usr/afs/backup/tapeconfig file, rather than 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.)

The command's arguments can be combined as indicated:

To preserve a volume's current contents and also create a new volume tohouse the restored version, use the -extension argument. The BackupSystem creates the new volume on the server and partition named by the-server and -partition arguments, assigns it the same name as thecurrent volume with the addition of the specified extension, and creates anew Volume Location Database (VLDB) entry for it. Creating a new volumeenables the administrator to compare the two versions.
To overwrite a volume's existing contents with the restored version, omitthe -extension argument, and specify the site as indicated:
To retain the current site, specify it with the -server and-partition arguments.
To move the volume to a different site while overwriting it, specify thenew site with the -server argument, -partition argument, orboth. The Backup System creates a new volume at that site, removes theexisting volume, and updates the site information in the volume's VLDBentry. The backup version of the volume is not removed automatically fromthe original site, if it exists. Use the vos remove command to removeit and the vos backup command to create a backup version at the newsite.
To restore a volume that no longer exists in the file system, specify itsname with the -volume argument and use the -server and -partitionarguments to place it at the desired site. The Backup System creates a newvolume and new VLDB entry.

In each case, the command sets each volume's creation date to the date andtime at which it restores it. The creation date appears in the Creationfield in the output from the vos examine and vos listvol commands.

If restoring all of the volumes that resided on a single partition, it isusually more efficient to use the backup diskrestore command. Ifrestoring multiple volumes to many different sites, it can be moreefficient to use the backup volsetrestore command.

By default, the backup volrestore command restores the most recent fulldump and all subsequent incremental dumps for each volume, bringing therestored volumes to the most current possible state. To restore thevolumes to their state at some time in the past, use the -dateargument. The Backup System restores the most recent full dump and eachsubsequent incremental dump for which the clone date of the volumeincluded in the dump is before the indicated date and time (the clone datetimestamp appears in the clone date field of the output from thebackup volinfo command). For backup and read-only volumes, the clonedate represents the time at which the volume was copied from itsread/write source; for read/write volumes, it represents the time at whichthe volume was locked for inclusion in the dump. The resemblance of arestored volume to its actual state at the indicated time depends on theamount of time that elapsed between the volume's clone date in the lasteligible dump and the specified time.

If the -volume argument specifies the base (read/write) form of thevolume name, the Backup System searches the Backup Database for the newestdump set that includes a dump of either the read/write or the backupversion of the volume. It restores the dumps of that version of thevolume, starting with the most recent full dump. If, in contrast, thevolume name explicitly includes the .backup or .readonly extension,the Backup System restores dumps of the corresponding volume version only.

To generate a list of the tapes the Backup System needs to perform therestore operation, without actually performing it, combine the -n flagwith the options to be used on the actual command.

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). If restoring multiple volumes, the same ordered list of port offsetsmust apply to all of them. If not, either issue this command separatelyfor each volume, or use the vos volsetrestore command after defininggroups of volumes that were dumped to compatible tape types. For furtherdiscussion, see the IBM AFS Administration Guide.

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. 


-server <destination machine>
Names the file server machine on which to restore each volume. If thisargument and the -partition argument indicate a site other than thecurrent site for each volume, and the -extension argument is not alsoprovided, the Backup System removes the existing volumes from theircurrent sites, places the restored contents at the specified site, andchanges the site information in the volume's VLDB entry.
-partition <destination partition>
Names the partition to which to restore each volume. If this argument andthe -server argument indicate a site other than the current site foreach volume, and the -extension argument is not also provided, theBackup System removes the existing volumes from their current sites,places the restored contents at the specified site, and changes the siteinformation in the volume's VLDB entry.
-volume <volume to restore>+
Names one or more volumes to restore, using the volume name as listed inthe Backup Database. Provide the base (read/write) name of each volume tohave the Backup System search the Backup Database for the newest dump setthat includes a dump of either the read/write or the backup version of thevolume; it restores the dumps of that version of the volume, starting withthe most recent full dump. If, in contrast, a volume name explicitlyincludes the .backup or .readonly extension, the Backup Systemrestores dumps of the corresponding volume version only.
-extension <new volume name extension>
Creates a new volume to house the restored data, with a name derived byappending the specified string to each volume named by the -volumeargument. The Backup System creates a new VLDB entry for the volume. Anystring other than .readonly or .backup is acceptable, but thecombination of the existing volume name and extension cannot exceed 22characters in length. To use a period to separate the extension from thename, specify it as the first character of the string (as in .rst, forexample).
-date <date from which to restore>+
Specifies a date and optionally time; the restored volume includes datafrom dumps performed before the date only. Provide a value in the formatmm/dd/yyyy [hh:MM], where the required mm/dd/yyyy portionindicates the month (mm), day (dd), and year (yyyy), and theoptional hh:MM portion indicates the hour and minutes in 24-hour format(for example, the value 14:36 represents 2:36 p.m.). If omitted, thetime defaults to 59 seconds after midnight (00:00:59 hours).

Valid values for the year range from 1970 to 2037; higher values arenot valid because the latest possible date in the standard UNIXrepresentation is in February 2038. The command interpreter automaticallyreduces any later date to the maximum value.

If this argument is omitted, the Backup System restores all possible dumpsincluding the most recently created.

-portoffset <TC port offest>+
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 the list of tapes that contain the dumps required by the restoreoperation, without actually performing the operation.
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 issuer includes the -n flag with the command, the followingstring appears at the head of the list of the tapes necessary to completethe restore operation.

   Tapes needed:


The following command restores the volume user.pat to partition /vicepaon machine

   % backup volrestore -server -partition a -volume user.pat
The following command restores the volumes user.smith and user.terryto partition /vicepb on machine, adding a .rstextension to each volume name and preserving the existing user.smithand user.terry volumes. Only dumps created before 5:00 p.m. on 31January 1998 are restored. (The command is shown here on multiple linesonly for legibility reasons.)

   % backup volrestore -server -partition b  \                       -volume user.smith user.terry  \                       -extension .rst -date 1/31/1998 17:00
The following command restores the volume user.pat to partition /vicepbon machine The Tape Coordinator with port offset 1 handlesthe tape containing the full dump; the Tape Coordinator with port offset 0handles all tapes containing incremental dumps. (The command is shown hereon two lines only for legibility reasons.)

   % backup volrestore -server -partition a  \                       -volume user.pat -portoffset 1 0


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_dump(8) manpage,the backup_diskrestore(8) manpage,the backup_volsetrestore(8) manpage,the butc(8) manpage,the vos_backup(1) manpage,the vos_remove(1) 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.