jimzah/openafs
1
0
Fork 0
mirror of https://git.openafs.org/openafs.git synced 2025-01-19 07:20:11 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
e3dfba8e6c
openafs/doc/man-pages/pod8/backup_volsetrestore.pod
Russ Allbery e3dfba8e6c man-page-conversion-20051208 
This is the initial conversion of the AFS Adminstrators Reference into POD
for use as man pages.  The man pages are now generated via pod2man from
regen.sh so that only those working from CVS have to have pod2man
available.  The Makefile only installs.  The pages have also been sorted
out into pod1, pod5, and pod8 directories, making conversion to the right
section of man page easier without maintaining a separate list and allowing
for names to be duplicated between pod5 and pod1 or pod8 (which will likely
be needed in a few cases).

This reconversion is done with a new script based on work by Chas Williams.
In some cases, the output is worse than the previous POD pages, but this is
a more comprehensive conversion.

This is only the first step, and this initial conversion has various
problems.  In addition, the file man pages that didn't have simple names
have not been converted in this pass and will be added later.  Some of the
man pages have syntax problems and all of them have formatting errors.  The
next editing pass, coming shortly, will clean up most of the remaining
mess.
2005-12-08 12:14:33 +00:00

433 lines
16 KiB
Plaintext
Raw Blame History

=head1 NAME
backup volsetrestore - Restores all volumes in a volume set
=head1 SYNOPSIS
B<backup volsetrestore> [B<-name> <I<volume set name>>] [-file <I<file name>>]
[B<-portoffset> <I<TC port offset>>+]
[-extension <I<new volume name extension>>]
[B<-n>] [B<-localauth>] [B<-cell> <I<cell name>>] [-help]
B<backup vols> [B<-na> <I<volume set name>>] [-f <I<file name>>]
[B<-p> <I<TC port offset>>+] [B<-e> <I<new volume name extension>>]
[B<-n>] [B<-l>] [B<-c> <I<cell name>>] [-h]
=head1 DESCRIPTION
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
B</usr/afs/backup/CFG_>I<device_name> file associated with the
specified port offset, then the B<backup volsetrestore> command
restores data from the backup data file listed for that port offset in the
Tape Coordinator's B</usr/afs/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 B<backup volrestore> command. If restoring
all volumes that resided on a single partition, it is usually more efficient
to use the B<backup diskrestore> command.
Indicate the volumes to restore by providing either the -name
argument or the B<-file> argument:
=over 4
=item *
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 B<-volumeset> option to the B<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 I<temporary> volume set, created by including
the B<-temporary> flag to the B<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.
=item *
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.
=back
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
B<-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). 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 B<backup volrestore> 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
I<IBM AFS Administration Guide>.
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 B<-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.
The -n flag produces a list of the volumes to be restored if the
B<-n> flag were not included, without actually restoring any
volumes. See the B<Output> section of this reference page for a
detailed description of the output, and suggestions on how to combine it most
effectively with the B<-file> and B<-name> arguments.
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 B<-name> argument to specify disjoint volume sets for each
command, or the B<-file> 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 changes required.
The Tape Coordinator's default response to this command is to access
the first tape it needs by invoking the B<MOUNT> instruction in the
local B</usr/afs/backup/CFG_>I<device_name> file, or by
prompting the backup operator to insert the tape if there is no
B<MOUNT> instruction. However, if the B<AUTOQUERY NO>
instruction appears in the B<CFG_>I<device_name> file, or if the
issuer of the B<butc> command included the B<-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 B<MOUNT> instruction or prompts the operator. It
also invokes the B<MOUNT> instruction or prompts for any additional
tapes needed to complete the restore operation; the backup operator must
arrange to provide them.
=head1 OPTIONS
=over 4
=item -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 B<-file> argument, but
not both.
=item -file
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 B<-name> argument, but not
both.
Each volume's entry must appear on its own (unbroken) line in the
file, and have the following format:
I<machine partition
volume> [I<comments...>]
where
=over 4
=item I<machine
>
Names the file server machine to which to restore the volume.
=item I<partition
>
Names the partition to which to restore the volume.
=item I<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
B<.backup> or B<.readonly> extension, the Backup
System restores dumps of that volume version only.
=item I<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.
=back
Do not use wildcards (for example, .*) in the
I<machine>, I<partition>, or I<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.
=item -extension
Creates a new volume for each volume specified by the -name or
B<-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 B<.readonly> or B<.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
B<.rst>, for example).
=item -portoffset
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 B<0> is just one of the values in the list,
provide it explicitly in the appropriate order.
=item -n
Displays a list of the volumes to be restored if the flag were not
included, without actually restoring them. The B<Output>
section of this reference page details the format of the output. When
combined with the B<-name> argument, its output is easily edited for
use as input to the B<-file> argument on a subsequent B<backup
volsetrestore> command.
=item -localauth
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The B<backup> command
interpreter presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory
B<backup> reference page.
=item -cell
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory B<backup> reference page.
=item -help
Prints the online help for this command. All other valid options
are ignored.
=back
=head1 OUTPUT
If the -n flag is not provided, the command displays a unique
task ID number for the operation, in two places:
=over 4
=item *
In the shell window, directly following the command line
=item *
In the Tape Coordinator window, if the butc process was started
at debug level 1
=back
The task ID number is not the same as the job ID number displayed by the
B<(backup) jobs> command when the B<(backup) volsetrestore>
command is 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 together, however.
The format of each line is as follows (the output is shown here on two
lines only for legibility reasons):
I<machine partition volume_dumped> # as I<volume_restored>; I<tape_name> (I<tape_ID>); \
pos I<position_number>; I<date>
where
=over 4
=item I<machine
>
Names the file server machine that currently houses the volume, as listed
in the VLDB.
=item I<partition
>
Names the partition that currently houses the volume, as listed in the
VLDB.
=item I<volume_dumped
>
Specifies the version (read/write or backup) of the volume that was
dumped, as listed in the Backup Database.
=item I<volume_restored
>
Specifies the name under which to restore the volume. The Backup
System only restores data to read/write volumes. If the
B<-extension> argument is included, then the specified extension
appears on the name in this field (for example,
C<user.pat.rst>).
=item I<tape_name
>
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.
=item I<tape_ID
>
The tape ID of the tape containing the dump of the volume, from the Backup
Database.
=item I<position_number
>
Specifies the dump's position on the tape (for example, C<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.
=item I<date
>
The date and time when the volume was dumped.
=back
One way to generate a file for use as input to the -file
argument is to combine the B<-name> and B<-n> options,
directing the output to a file. The I<IBM AFS 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 B<-file>
argument.
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
B<-file> argument, or appear in the VLDB as a match to a volume entry
in the volume set named by the B<-name> argument.
=head1 EXAMPLES
The following command restores all volumes included in entries in the
volume set named B<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
Starting 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 B</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:
fs1.abc.com b user.pat
fs1.abc.com b user.terry
fs1.abc.com b user.smith
fs2.abc.com c user.jones
. . .
. . .
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the /usr/afs/etc/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 B<-localauth> flag is included, the issuer must
instead be logged on to a server machine as the local superuser
B<root>.
=head1 SEE ALSO
L<backup(1)>,
L<backup_addvolentry(1)>,
L<backup_addvolset(1)>,
L<backup_diskrestore(1)>,
L<backup_dump(1)>,
L<backup_volrestore(1)>,
L<butc(1)>
=head1 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.
Reference in New Issue View Git Blame Copy Permalink