backup_volsetrestore - Restores all volumes in a volume set
<volume set name
<TC port offset
<new volume name extension
<volume set name
<TC port offset
<new volume name extension
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 "FILE YES" instruction appears in the
with the specified port offset, then the backup volsetrestore
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
Indicate the volumes to restore by providing either the -name
- 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
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
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 OpenAFS
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.
flag produces a list of the volumes to be restored if the
flag were not included, without actually restoring any volumes. See
"OUTPUT" for a detailed description of the output, and suggestions
on how to combine it most effectively with the -file
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
argument to specify disjoint volume sets for each command, or the
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
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
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
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
- -name <volume set name>
- 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
- -file <file name>
- 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
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
- 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 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 name explicitly includes
the ".backup" or ".readonly" extension, the Backup
System restores dumps of that volume version only.
- <comments> ...
- Is any other text. The Backup System ignores any text on
each line that appears after the volume name, so this field can be used
for notes helpful to 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 to name the same volume, but the Backup System processes
only the first of them.
- -extension <new volume name
- Creates a new volume for each volume specified by the
-name or -file argument, to house the restored data from
that volume. The Backup System derives the new volume's name by appending
the specified string to the read/write base name, and creates a new VLDB
volume entry. It preserves the contents of each existing volume. Any
string other than ".readonly" or ".backup" is
acceptable, but the combination of the base 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).
- -portoffset <TC port offset>+
- 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.
- Displays a list of the volumes to be restored if the flag
were not included, without actually restoring them. "OUTPUT"
details the format of the output. When combined with the -name
argument, its output is easily edited for use as input to the -file
argument on a subsequent backup volsetrestore command.
- 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
- Prints the online help for this command. All other valid
options are ignored.
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
- 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
command when the backup volsetrestore
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
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>
- Names the file server machine that currently houses the
volume, as listed in the VLDB.
- Names the partition that currently houses the volume, as
listed in the VLDB.
- Specifies the version (read/write or backup) of the volume
that was dumped, as listed in the Backup Database.
- Specifies the name under which to restore the volume. The
Backup System only restores data to read/write volumes. If the
-extension argument is included, then the specified extension
appears on the name in this field (for example,
- Names the tape containing the dump of the volume, from the
Backup Database. If the tape has a permanent name, it appears here;
otherwise, it is the AFS tape name.
- The tape ID of the tape containing the dump of the volume,
from the Backup Database.
- Specifies the dump's position on the tape (for example, 31
indicates that 30 volume dumps precede the current one on the tape). If
the dump was written to a backup data file, this number is the ordinal of
the 16 KB-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 to
combine the -name
options, directing the output to a
file. The OpenAFS 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
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
The following command restores all volumes included in entries in the volume set
named "data.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
backup: task ID of restore operation: 112
backup: Finished doing restore
The following command restores all volumes that have entries in the file named
% backup volsetrestore -file /tmp/restore
backup: task ID of restore operation: 113
backup: Finished doing restore
file has the following contents:
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
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
flag is included, the issuer must instead be logged on
to a server machine as the local superuser "root".
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.