NAME

       backup_volrestore - Restores one or more volumes

SYNOPSIS

       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>+] [-dryrun | -n]
           [-usedump <specify the dumpID to restore from>]
           [-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>+]
           [-u <specify the dumpID to restore from>]
           [-dryrun | -n] [-l] [-c <cell name>] [-h]

DESCRIPTION

       The backup volrestore command restores the contents of one or more volumes to the site
       indicated by the -server and -partition arguments. Use the command either to overwrite the
       contents of existing volumes with the restored data or to create new volumes while
       retaining the existing ones. The specified site does not have to be the current site for
       the volumes.

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

       The command's arguments can be combined as indicated:

       •   To preserve a volume's current contents and also create a new volume to house the
           restored version, use the -extension argument.  The Backup System creates the new
           volume on the server and partition named by the -server and -partition arguments,
           assigns it the same name as the current volume with the addition of the specified
           extension, and creates a new Volume Location Database (VLDB) entry for it.  Creating a
           new volume enables the administrator to compare the two versions.

       •   To overwrite a volume's existing contents with the restored version, omit the
           -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 the new site
               with the -server argument, -partition argument, or both. The Backup System creates
               a new volume at that site, removes the existing volume, and updates the site
               information in the volume's VLDB entry. The backup version of the volume is not
               removed automatically from the original site, if it exists. Use the vos remove
               command to remove it and the vos backup command to create a backup version at the
               new site.

       •   To restore a volume that no longer exists in the file system, specify its name with
           the -volume argument and use the -server and -partition arguments to place it at the
           desired site. The Backup System creates a new volume and new VLDB entry.

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

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

       By default, the backup volrestore command restores the most recent full dump and all
       subsequent incremental dumps for each volume, bringing the restored volumes to the most
       current possible state. To restore the volumes to their state at some time in the past,
       use the -date argument. The Backup System restores the most recent full dump and each
       subsequent incremental dump for which the clone date of the volume included in the dump is
       before the indicated date and time (the clone date timestamp appears in the "clone date"
       field of the output from the backup volinfo command). For backup and read-only volumes,
       the clone date represents the time at which the volume was copied from its read/write
       source; for read/write volumes, it represents the time at which the volume was locked for
       inclusion in the dump. The resemblance of a restored volume to its actual state at the
       indicated time depends on the amount of time that elapsed between the volume's clone date
       in the last eligible dump and the specified time.

       If the -volume argument specifies the base (read/write) form of the volume name, the
       Backup System searches the Backup Database for the newest dump set that includes a dump of
       either the read/write or the backup version of the volume. It restores the dumps of that
       version of the volume, starting with the most recent full dump. If, in contrast, the
       volume 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 the restore operation,
       without actually performing it, combine the -dryrun flag with the options to be used on
       the actual command.

       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). If restoring multiple volumes, the same ordered list of port offsets must
       apply to all of them. If not, either issue this command separately for each volume, or use
       the vos volsetrestore command after defining groups of volumes that were dumped to
       compatible tape types. For further discussion, see the OpenAFS Administration Guide.

       The Tape Coordinator's default response to this command is to access the first tape it
       needs by invoking the MOUNT 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 "MOUNT" instruction. However, if the "AUTOQUERY 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
       "MOUNT" instruction or prompts the operator. It also invokes the "MOUNT" instruction or
       prompts for any additional tapes needed to complete the restore operation; the backup
       operator must arrange to provide them.

OPTIONS

       -server <destination machine>
           Names the file server machine on which to restore each volume. If this argument and
           the -partition argument indicate a site other than the current site for each volume,
           and the -extension argument is not also provided, the Backup System removes the
           existing volumes from their current sites, places the restored contents at the
           specified site, and changes the site information in the volume's VLDB entry.

       -partition <destination partition>
           Names the partition to which to restore each volume. If this argument and the -server
           argument indicate a site other than the current site for each volume, and the
           -extension argument is not also provided, the Backup System removes the existing
           volumes from their current sites, places the restored contents at the specified site,
           and changes the site information in the volume's VLDB entry.

       -volume <volume to restore>+
           Names one or more volumes to restore, using the volume name as listed in the Backup
           Database. Provide the base (read/write) name of each volume to have the Backup System
           search the Backup Database for the newest dump set that includes a dump of either the
           read/write or the backup version of the volume; it restores the dumps of that version
           of the volume, starting with the most recent full dump. If, in contrast, a volume name
           explicitly includes the ".backup" or ".readonly" extension, the Backup System restores
           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 by appending the
           specified string to each volume named by the -volume argument. The Backup System
           creates a new VLDB entry for the volume. Any string other than ".readonly" or
           ".backup" is acceptable, but the combination of the existing volume name and extension
           cannot exceed 22 characters in length. To use a period to separate the extension from
           the name, specify it as the first character of the string (as in ".rst", for example).

       -date <date from which to restore>+
           Specifies a date and optionally time; the restored volume includes data from dumps
           performed before the date only. Provide a value in the format mm/dd/yyyy [hh:MM],
           where the required mm/dd/yyyy portion indicates the month (mm), day (dd), and year
           (yyyy), and the optional 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, the time
           defaults to 59 seconds after midnight (00:00:59 hours).

           Valid values for the year range from 1970 to 2037; higher values are not valid because
           the latest possible date in the standard UNIX representation is in February 2038. The
           command interpreter automatically reduces any later date to the maximum value.

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

       -usedump <dumpID>
           Specifies the dumpID of the specific dump to use to restore the volume. If this option
           is not specified, we will find the appropriate dump to restore, according to the logic
           in the -date option.

       -portoffset <TC port offest>+
           Specifies one or more port offset numbers (up to a maximum of 128), each corresponding
           to a Tape Coordinator to use in the operation. If there is more than one value, the
           Backup System uses the first one when restoring the full dump of each volume, the
           second one when restoring the level 1 incremental dump of each volume, and so on. It
           uses the final value in the list when restoring dumps at the corresponding depth in
           the dump hierarchy and all dumps at lower levels.

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

       -dryrun | -n
           Displays the list of tapes that contain the dumps required by the restore operation,
           without actually performing the operation.

       -localauth
           Constructs a server ticket using a key from the local /etc/openafs/server/KeyFile
           file. The backup command interpreter presents it to the Backup Server, Volume Server
           and VL Server during mutual authentication. Do not combine this flag with the -cell
           argument. For more details, see backup(8).

       -cell <cell name>
           Names the cell in which to run the command. Do not combine this argument with the
           -localauth flag. For more details, see backup(8).

       -help
           Prints the online help for this command. All other valid options are ignored.

OUTPUT

       If the issuer includes the -dryrun flag with the command, the following string appears at
       the head of the list of the tapes necessary to complete the restore operation.

          Tapes needed:

EXAMPLES

       The following command restores the volume user.pat to partition /vicepa on machine
       "fs5.example.com":

          % backup volrestore -server fs5.example.com -partition a -volume user.pat

       The following command restores the volumes "user.smith" and "user.terry" to partition
       /vicepb on machine "fs4.example.com", adding a ".rst" extension to each volume name and
       preserving the existing "user.smith" and "user.terry" volumes.  Only dumps created before
       5:00 p.m. on 31 January 1998 are restored. (The command is shown here on multiple lines
       only for legibility reasons.)

          % backup volrestore -server fs4.example.com -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 /vicepb on machine
       "fs4.example.com". The Tape Coordinator with port offset 1 handles the tape containing the
       full dump; the Tape Coordinator with port offset 0 handles all tapes containing
       incremental dumps. (The command is shown here on two lines only for legibility reasons.)

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

PRIVILEGE REQUIRED

       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 "root".

SEE ALSO

       butc(5), backup(8), backup_dump(8), backup_diskrestore(8), backup_volsetrestore(8),
       butc(8), vos_backup(1), vos_remove(1)

COPYRIGHT

       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.