--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
+<HTML><HEAD>
+<TITLE>Administration Reference</TITLE>
+<!-- Begin Header Records ========================================== -->
+<!-- /tmp/idwt3672/auarf000.scr converted by idb2h R4.2 (359) ID -->
+<!-- Workbench Version (AIX) on 3 Oct 2000 at 16:18:30 -->
+<META HTTP-EQUIV="updated" CONTENT="Tue, 03 Oct 2000 16:18:29">
+<META HTTP-EQUIV="review" CONTENT="Wed, 03 Oct 2001 16:18:29">
+<META HTTP-EQUIV="expires" CONTENT="Thu, 03 Oct 2002 16:18:29">
+</HEAD><BODY>
+<!-- (C) IBM Corporation 2000. All Rights Reserved -->
+<BODY bgcolor="ffffff">
+<!-- End Header Records ============================================ -->
+<A NAME="Top_Of_Page"></A>
+<H1>Administration Reference</H1>
+<HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf091.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Bot_Of_Page"><IMG SRC="../bot.gif" BORDER="0" ALT="[Bottom of Topic]"></A> <A HREF="auarf093.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
+<P>
+<H2><A NAME="HDRBK_VOLSETRESTORE" HREF="auarf002.htm#ToC_106">backup volsetrestore</A></H2>
+<A NAME="IDX4428"></A>
+<A NAME="IDX4429"></A>
+<A NAME="IDX4430"></A>
+<A NAME="IDX4431"></A>
+<A NAME="IDX4432"></A>
+<A NAME="IDX4433"></A>
+<A NAME="IDX4434"></A>
+<P><STRONG>Purpose</STRONG>
+<P>Restores all volumes in a volume set
+<P><STRONG>Synopsis</STRONG>
+<PRE><B>backup volsetrestore</B> [<B>-name</B> <<VAR>volume set name</VAR>>] [<B>-file</B> <<VAR>file name</VAR>>]
+ [<B>-portoffset</B> <<VAR>TC port offset</VAR>><SUP>+</SUP>]
+ [<B>-extension</B> <<VAR>new volume name extension</VAR>>]
+ [<B>-n</B>] [<B>-localauth</B>] [<B>-cell</B> <<VAR>cell name</VAR>>] [<B>-help</B>]
+
+<B>backup vols</B> [<B>-na</B> <<VAR>volume set name</VAR>>] [<B>-f</B> <<VAR>file name</VAR>>]
+ [<B>-p</B> <<VAR>TC port offset</VAR>><SUP>+</SUP>] [<B>-e</B> <<VAR>new volume name extension</VAR>>]
+ [<B>-n</B>] [<B>-l</B>] [<B>-c</B> <<VAR>cell name</VAR>>] [<B>-h</B>]
+</PRE>
+<P><STRONG>Description</STRONG>
+<P>The <B>backup volsetrestore</B> 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.
+<P>(If the <B>FILE YES</B> instruction appears in the
+<B>/usr/afs/backup/CFG_</B><VAR>device_name</VAR> file associated with the
+specified port offset, then the <B>backup volsetrestore</B> command
+restores data from the backup data file listed for that port offset in the
+Tape Coordinator's <B>/usr/afs/backup/tapeconfig</B> 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.)
+<P>If restoring one or more volumes to a single site only, it is usually more
+efficient to use the <B>backup volrestore</B> command. If restoring
+all volumes that resided on a single partition, it is usually more efficient
+to use the <B>backup diskrestore</B> command.
+<P>Indicate the volumes to restore by providing either the <B>-name</B>
+argument or the <B>-file</B> argument:
+<UL>
+<P><LI>The <B>-name</B> 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.
+<P>It is not required that the volume set was previously used to back up
+volumes (was used as the <B>-volumeset</B> option to the <B>backup
+dump</B> 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</I> volume set, created by including
+the <B>-temporary</B> flag to the <B>backup addvolset</B> 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.
+<P>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.
+<P><LI>The <B>-file</B> 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.
+</UL>
+<P>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</B> 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</B> 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</I>.
+<P>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</B> 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.
+<P>The <B>-n</B> flag produces a list of the volumes to be restored if the
+<B>-n</B> flag were not included, without actually restoring any
+volumes. See the <B>Output</B> 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</B> and <B>-name</B> arguments.
+<P>The execution time for a <B>backup volsetrestore</B> 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</B> argument to specify disjoint volume sets for each
+command, or the <B>-file</B> 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.
+<P>The Tape Coordinator's default response to this command is to access
+the first tape it needs by invoking the <B>MOUNT</B> instruction in the
+local <B>/usr/afs/backup/CFG_</B><VAR>device_name</VAR> file, or by
+prompting the backup operator to insert the tape if there is no
+<B>MOUNT</B> instruction. However, if the <B>AUTOQUERY NO</B>
+instruction appears in the <B>CFG_</B><VAR>device_name</VAR> file, or if the
+issuer of the <B>butc</B> command included the <B>-noautoquery</B>
+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</B> instruction or prompts the operator. It
+also invokes the <B>MOUNT</B> instruction or prompts for any additional
+tapes needed to complete the restore operation; the backup operator must
+arrange to provide them.
+<P><STRONG>Options</STRONG>
+<DL>
+<P><DT><B>-name
+</B><DD>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</B> argument, but
+not both.
+<P><DT><B>-file
+</B><DD>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</B> argument, but not
+both.
+<P>Each volume's entry must appear on its own (unbroken) line in the
+file, and have the following format:
+<PRE> <VAR>machine partition
+ volume</VAR> [<VAR>comments...</VAR>]
+
+</PRE>
+<P>
+<P>where
+<DL>
+<P><DT><B><VAR>machine</VAR>
+</B><DD>Names the file server machine to which to restore the volume.
+<P><DT><B><VAR>partition</VAR>
+</B><DD>Names the partition to which to restore the volume.
+<P><DT><B><VAR>volume</VAR>
+</B><DD>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</B> or <B>.readonly</B> extension, the Backup
+System restores dumps of that volume version only.
+<P><DT><B><VAR>comments...</VAR>
+</B><DD>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.
+</DL>
+<P>
+<P>Do not use wildcards (for example, <B>.*</B>) in the
+<VAR>machine</VAR>, <VAR>partition</VAR>, or <VAR>volume</VAR> 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.
+<P><DT><B>-extension
+</B><DD>Creates a new volume for each volume specified by the <B>-name</B> or
+<B>-file</B> 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</B> or <B>.backup</B> 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</B>, for example).
+<P><DT><B>-portoffset
+</B><DD>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.
+<P>Provide this argument unless the default value of 0 (zero) is appropriate
+for all dumps. If <B>0</B> is just one of the values in the list,
+provide it explicitly in the appropriate order.
+<P><DT><B>-n
+</B><DD>Displays a list of the volumes to be restored if the flag were not
+included, without actually restoring them. The <B>Output</B>
+section of this reference page details the format of the output. When
+combined with the <B>-name</B> argument, its output is easily edited for
+use as input to the <B>-file</B> argument on a subsequent <B>backup
+volsetrestore</B> command.
+<P><DT><B>-localauth
+</B><DD>Constructs a server ticket using a key from the local
+<B>/usr/afs/etc/KeyFile</B> file. The <B>backup</B> 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</B> argument. For more details, see the introductory
+<B>backup</B> reference page.
+<P><DT><B>-cell
+</B><DD>Names the cell in which to run the command. Do not combine this
+argument with the <B>-localauth</B> flag. For more details, see the
+introductory <B>backup</B> reference page.
+<P><DT><B>-help
+</B><DD>Prints the online help for this command. All other valid options
+are ignored.
+</DL>
+<P><STRONG>Output</STRONG>
+<P>If the <B>-n</B> flag is not provided, the command displays a unique
+task ID number for the operation, in two places:
+<UL>
+<P><LI>In the shell window, directly following the command line
+<P><LI>In the Tape Coordinator window, if the <B>butc</B> process was started
+at debug level 1
+</UL>
+<P>The task ID number is not the same as the job ID number displayed by the
+<B>(backup) jobs</B> command when the <B>(backup) volsetrestore</B>
+command is issued in interactive mode. The Backup System does not
+assign either type of ID number until the restoration process actually
+begins.
+<P>When the <B>-n</B> 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.
+<P>The format of each line is as follows (the output is shown here on two
+lines only for legibility reasons):
+<PRE> <VAR>machine partition volume_dumped</VAR> # as <VAR>volume_restored</VAR>; <VAR>tape_name</VAR> (<VAR>tape_ID</VAR>); \
+ pos <VAR>position_number</VAR>; <VAR>date</VAR>
+
+</PRE>
+<P>where
+<DL>
+<P><DT><B><VAR>machine</VAR>
+</B><DD>Names the file server machine that currently houses the volume, as listed
+in the VLDB.
+<P><DT><B><VAR>partition</VAR>
+</B><DD>Names the partition that currently houses the volume, as listed in the
+VLDB.
+<P><DT><B><VAR>volume_dumped</VAR>
+</B><DD>Specifies the version (read/write or backup) of the volume that was
+dumped, as listed in the Backup Database.
+<P><DT><B><VAR>volume_restored</VAR>
+</B><DD>Specifies the name under which to restore the volume. The Backup
+System only restores data to read/write volumes. If the
+<B>-extension</B> argument is included, then the specified extension
+appears on the name in this field (for example,
+<TT>user.pat.rst</TT>).
+<P><DT><B><VAR>tape_name</VAR>
+</B><DD>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.
+<P><DT><B><VAR>tape_ID</VAR>
+</B><DD>The tape ID of the tape containing the dump of the volume, from the Backup
+Database.
+<P><DT><B><VAR>position_number</VAR>
+</B><DD>Specifies the dump's position on the tape (for example, <TT>31</TT>
+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.
+<P><DT><B><VAR>date</VAR>
+</B><DD>The date and time when the volume was dumped.
+</DL>
+<P>One way to generate a file for use as input to the <B>-file</B>
+argument is to combine the <B>-name</B> and <B>-n</B> options,
+directing the output to a file. The <I>IBM AFS Administration
+Guide</I> 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</B>
+argument.
+<P>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</B> argument, or appear in the VLDB as a match to a volume entry
+in the volume set named by the <B>-name</B> argument.
+<P><STRONG>Examples</STRONG>
+<P>The following command restores all volumes included in entries in the
+volume set named <B>data.restore</B>, 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.
+<PRE> % <B>backup volsetrestore -name data.restore</B>
+ Starting restore
+ backup: task ID of restore operation: 112
+ backup: Finished doing restore
+
+</PRE>
+<P>The following command restores all volumes that have entries in the file
+named <B>/tmp/restore</B>:
+<PRE> % <B>backup volsetrestore -file /tmp/restore</B>
+ Starting restore
+ backup: task ID of restore operation: 113
+ backup: Finished doing restore
+
+</PRE>
+<P>The <B>/tmp/restore</B> file has the following contents:
+<PRE> fs1.abc.com b user.pat
+ fs1.abc.com b user.terry
+ fs1.abc.com b user.smith
+ fs2.abc.com c user.jones
+ . . .
+ . . .
+
+</PRE>
+<P><STRONG>Privilege Required</STRONG>
+<P>The issuer must be listed in the <B>/usr/afs/etc/UserList</B> 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</B> flag is included, the issuer must
+instead be logged on to a server machine as the local superuser
+<B>root</B>.
+<P><STRONG>Related Information</STRONG>
+<P><A HREF="auarf060.htm#HDRBK_INTRO">backup</A>
+<P><A HREF="auarf063.htm#HDRBK_ADDVOLENTRY">backup addvolentry</A>
+<P><A HREF="auarf064.htm#HDRBK_ADDVOLSET">backup addvolset</A>
+<P><A HREF="auarf072.htm#HDRBK_DISKRESTORE">backup diskrestore</A>
+<P><A HREF="auarf073.htm#HDRBK_DUMP">backup dump</A>
+<P><A HREF="auarf091.htm#HDRBK_VOLRESTORE">backup volrestore</A>
+<P><A HREF="auarf126.htm#HDRBUTC">butc</A>
+<P>
+<HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf091.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Top_Of_Page"><IMG SRC="../top.gif" BORDER="0" ALT="[Top of Topic]"></A> <A HREF="auarf093.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
+<!-- Begin Footer Records ========================================== -->
+<P><HR><B>
+<br>© <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A> All Rights Reserved
+</B>
+<!-- End Footer Records ============================================ -->
+<A NAME="Bot_Of_Page"></A>
+</BODY></HTML>
git://git.openafs.org / openafs.git / blobdiff