Provided by: openafs-client_1.4.12.1+dfsg-2_i386 bug

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>+] [-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]

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 -n 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 IBM AFS 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.

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

       -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 -n 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.abc.com":

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

       The following command restores the volumes "user.smith" and
       "user.terry" to partition /vicepb on machine "fs4.abc.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.abc.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.abc.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.abc.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.