1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
3 <TITLE>Administration Reference</TITLE>
4 <!-- Begin Header Records ========================================== -->
5 <!-- /tmp/idwt3672/auarf000.scr converted by idb2h R4.2 (359) ID -->
6 <!-- Workbench Version (AIX) on 3 Oct 2000 at 16:18:30 -->
7 <META HTTP-EQUIV="updated" CONTENT="Tue, 03 Oct 2000 16:18:29">
8 <META HTTP-EQUIV="review" CONTENT="Wed, 03 Oct 2001 16:18:29">
9 <META HTTP-EQUIV="expires" CONTENT="Thu, 03 Oct 2002 16:18:29">
11 <!-- (C) IBM Corporation 2000. All Rights Reserved -->
12 <BODY bgcolor="ffffff">
13 <!-- End Header Records ============================================ -->
14 <A NAME="Top_Of_Page"></A>
15 <H1>Administration Reference</H1>
16 <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>
18 <H2><A NAME="HDRBK_VOLSETRESTORE" HREF="auarf002.htm#ToC_106">backup volsetrestore</A></H2>
19 <A NAME="IDX4428"></A>
20 <A NAME="IDX4429"></A>
21 <A NAME="IDX4430"></A>
22 <A NAME="IDX4431"></A>
23 <A NAME="IDX4432"></A>
24 <A NAME="IDX4433"></A>
25 <A NAME="IDX4434"></A>
26 <P><STRONG>Purpose</STRONG>
27 <P>Restores all volumes in a volume set
28 <P><STRONG>Synopsis</STRONG>
29 <PRE><B>backup volsetrestore</B> [<B>-name</B> <<VAR>volume set name</VAR>>] [<B>-file</B> <<VAR>file name</VAR>>]
30 [<B>-portoffset</B> <<VAR>TC port offset</VAR>><SUP>+</SUP>]
31 [<B>-extension</B> <<VAR>new volume name extension</VAR>>]
32 [<B>-n</B>] [<B>-localauth</B>] [<B>-cell</B> <<VAR>cell name</VAR>>] [<B>-help</B>]
34 <B>backup vols</B> [<B>-na</B> <<VAR>volume set name</VAR>>] [<B>-f</B> <<VAR>file name</VAR>>]
35 [<B>-p</B> <<VAR>TC port offset</VAR>><SUP>+</SUP>] [<B>-e</B> <<VAR>new volume name extension</VAR>>]
36 [<B>-n</B>] [<B>-l</B>] [<B>-c</B> <<VAR>cell name</VAR>>] [<B>-h</B>]
38 <P><STRONG>Description</STRONG>
39 <P>The <B>backup volsetrestore</B> command restores the complete contents
40 of a group of read/write volumes to the file system, by restoring data from
41 the last full dump and all subsequent incremental dumps of each volume.
42 It is most useful for recovering from loss of data on multiple partitions,
43 since it can restore each of a defined set of volumes to a different
45 <P>(If the <B>FILE YES</B> instruction appears in the
46 <B>/usr/afs/backup/CFG_</B><VAR>device_name</VAR> file associated with the
47 specified port offset, then the <B>backup volsetrestore</B> command
48 restores data from the backup data file listed for that port offset in the
49 Tape Coordinator's <B>/usr/afs/backup/tapeconfig</B> file, instead of
50 from tape. For the sake of clarity, the following text refers to tapes
51 only, but the Backup System handles backup data files in much the same
53 <P>If restoring one or more volumes to a single site only, it is usually more
54 efficient to use the <B>backup volrestore</B> command. If restoring
55 all volumes that resided on a single partition, it is usually more efficient
56 to use the <B>backup diskrestore</B> command.
57 <P>Indicate the volumes to restore by providing either the <B>-name</B>
58 argument or the <B>-file</B> argument:
60 <P><LI>The <B>-name</B> argument names a volume set. The Backup System
61 restores all volumes listed in the Volume Location Database (VLDB) that match
62 the server, partition, and volume name criteria defined in the volume
63 set's volume entries, and for which dumps are available. It
64 restores the volumes to their current site (machine and partition), and by
65 default overwrites the existing volume contents.
66 <P>It is not required that the volume set was previously used to back up
67 volumes (was used as the <B>-volumeset</B> option to the <B>backup
68 dump</B> command). It can be defined especially to match the volumes
69 that need to be restored with this command, and that is usually the better
70 choice. Indeed, a <I>temporary</I> volume set, created by including
71 the <B>-temporary</B> flag to the <B>backup addvolset</B> command, can
72 be especially useful in this context. A temporary volume set is not
73 added to the Backup Database and exists only during the current interactive
74 backup session, which is suitable if the volume set is needed only to complete
75 the single restore operation initialized by this command.
76 <P>The reason that a specially defined volume set is probably better is that
77 volume sets previously defined for use in dump operations usually match the
78 backup version of volumes, whereas for a restore operation it is best to
79 define volume entries that match the base (read/write) name. In that
80 case, the Backup System searches the Backup Database for the newest dump set
81 that includes either the read/write or the backup version of the
82 volume. If, in contrast, a volume entry explicitly matches the
83 volume's backup or read-only version, the Backup System restores dumps of
84 that volume version only.
85 <P><LI>The <B>-file</B> argument names a file that lists specific volumes and
86 the site to which to restore each. The volume name must match the name
87 used in Backup Database dump records rather than in the VLDB, if they differ,
88 because the Backup System does not look up volumes in the VLDB. The
89 specified site can be different than the volume's current one; in
90 that case, the Backup System removes the current version of the volume and
91 updates the volume's location information in the VLDB.
93 <P>If all of the full and incremental dumps of all relevant volumes were not
94 written to a type of tape that a single Tape Coordinator can read, use the
95 <B>-portoffset</B> argument to list multiple port offset numbers in the
96 order in which the tapes are needed (first list the port offset for the full
97 dump, second the port offset for the level 1 incremental dump, and so
98 on). This implies that the full dumps of all relevant volumes must have
99 been written to a type of tape that the first Tape Coordinator can read, the
100 level 1 incremental dumps to a type of tape the second Tape Coordinator can
101 read, and so on. If dumps are on multiple incompatible tape types, use
102 the <B>backup volrestore</B> command to restore individual volumes, or use
103 this command after defining new volume sets that group together volumes that
104 were dumped to compatible tape types. For further discussion, see the
105 <I>IBM AFS Administration Guide</I>.
106 <P>By default, the Backup System overwrites the contents of an existing volume
107 with the restored data. To create a new volume to house the restored
108 version instead, use the <B>-extension</B> argument. The Backup
109 System derives the new volume's name by adding the specified extension to
110 the read/write base name, and creates a new VLDB entry. The command
111 does not affect the existing volume in any way. However, if a volume
112 with the specified extension also already exists, the command overwrites
114 <P>The <B>-n</B> flag produces a list of the volumes to be restored if the
115 <B>-n</B> flag were not included, without actually restoring any
116 volumes. See the <B>Output</B> section of this reference page for a
117 detailed description of the output, and suggestions on how to combine it most
118 effectively with the <B>-file</B> and <B>-name</B> arguments.
119 <P>The execution time for a <B>backup volsetrestore</B> command depends on
120 the number of volumes to be restored and the amount of data in them, but it
121 can take hours to restore a large number of volumes. One way to reduce
122 the time is to run multiple instances of the command simultaneously, either
123 using the <B>-name</B> argument to specify disjoint volume sets for each
124 command, or the <B>-file</B> argument to name files that list different
125 volumes. This is possible if there are multiple available Tape
126 Coordinators that can read the required tapes. Depending on how the
127 volumes to be restored were dumped to tape, specifying disjoint volume sets
128 can also reduce the number of tape changes required.
129 <P>The Tape Coordinator's default response to this command is to access
130 the first tape it needs by invoking the <B>MOUNT</B> instruction in the
131 local <B>/usr/afs/backup/CFG_</B><VAR>device_name</VAR> file, or by
132 prompting the backup operator to insert the tape if there is no
133 <B>MOUNT</B> instruction. However, if the <B>AUTOQUERY NO</B>
134 instruction appears in the <B>CFG_</B><VAR>device_name</VAR> file, or if the
135 issuer of the <B>butc</B> command included the <B>-noautoquery</B>
136 flag, the Tape Coordinator instead expects the tape to be in the device
137 already. If it is not, or is the wrong tape, the Tape Coordinator
138 invokes the <B>MOUNT</B> instruction or prompts the operator. It
139 also invokes the <B>MOUNT</B> instruction or prompts for any additional
140 tapes needed to complete the restore operation; the backup operator must
141 arrange to provide them.
142 <P><STRONG>Options</STRONG>
145 </B><DD>Names a volume set to restore. The Backup System restores all of
146 the volumes listed in the VLDB that match the volume set's volume
147 entries. Provide this argument or the <B>-file</B> argument, but
150 </B><DD>Specifies the full pathname of a file that lists one or more volumes and
151 the site (file server machine and partition) to which to restore each.
152 Use either this argument or the <B>-name</B> argument, but not
154 <P>Each volume's entry must appear on its own (unbroken) line in the
155 file, and have the following format:
156 <PRE> <VAR>machine partition
157 volume</VAR> [<VAR>comments...</VAR>]
163 <P><DT><B><VAR>machine</VAR>
164 </B><DD>Names the file server machine to which to restore the volume.
165 <P><DT><B><VAR>partition</VAR>
166 </B><DD>Names the partition to which to restore the volume.
167 <P><DT><B><VAR>volume</VAR>
168 </B><DD>Names the volume to restore. It is generally best to specify the
169 base (read/write) name of each volume. In this case, the Backup System
170 searches the Backup Database for the newest dump set that includes a dump of
171 either the read/write or the backup version of the volume. It restores
172 the dumps of that version of the volume, starting with the most recent full
173 dump. If, in contrast, the name explicitly includes the
174 <B>.backup</B> or <B>.readonly</B> extension, the Backup
175 System restores dumps of that volume version only.
176 <P><DT><B><VAR>comments...</VAR>
177 </B><DD>Is any other text. The Backup System ignores any text on each line
178 that appears after the volume name, so this field can be used for notes
179 helpful to the backup operator or other administrator.
182 <P>Do not use wildcards (for example, <B>.*</B>) in the
183 <VAR>machine</VAR>, <VAR>partition</VAR>, or <VAR>volume</VAR> fields. It is
184 acceptable for multiple lines in the file to name the same volume, but the
185 Backup System processes only the first of them.
187 </B><DD>Creates a new volume for each volume specified by the <B>-name</B> or
188 <B>-file</B> argument, to house the restored data from that volume.
189 The Backup System derives the new volume's name by appending the
190 specified string to the read/write base name, and creates a new VLDB volume
191 entry. It preserves the contents of each existing volume. Any
192 string other than <B>.readonly</B> or <B>.backup</B> is
193 acceptable, but the combination of the base name and extension cannot exceed
194 22 characters in length. To use a period to separate the extension from
195 the name, specify it as the first character of the string (as in
196 <B>.rst</B>, for example).
197 <P><DT><B>-portoffset
198 </B><DD>Specifies one or more port offset numbers (up to a maximum of 128), each
199 corresponding to a Tape Coordinator to use in the operation. If there
200 is more than one value, the Backup System uses the first one when restoring
201 the full dump of each volume, the second one when restoring the level 1
202 incremental dump of each volume, and so on. It uses the final value in
203 the list when restoring dumps at the corresponding depth in the dump hierarchy
204 and all dumps at lower levels.
205 <P>Provide this argument unless the default value of 0 (zero) is appropriate
206 for all dumps. If <B>0</B> is just one of the values in the list,
207 provide it explicitly in the appropriate order.
209 </B><DD>Displays a list of the volumes to be restored if the flag were not
210 included, without actually restoring them. The <B>Output</B>
211 section of this reference page details the format of the output. When
212 combined with the <B>-name</B> argument, its output is easily edited for
213 use as input to the <B>-file</B> argument on a subsequent <B>backup
214 volsetrestore</B> command.
216 </B><DD>Constructs a server ticket using a key from the local
217 <B>/usr/afs/etc/KeyFile</B> file. The <B>backup</B> command
218 interpreter presents it to the Backup Server, Volume Server and VL Server
219 during mutual authentication. Do not combine this flag with the
220 <B>-cell</B> argument. For more details, see the introductory
221 <B>backup</B> reference page.
223 </B><DD>Names the cell in which to run the command. Do not combine this
224 argument with the <B>-localauth</B> flag. For more details, see the
225 introductory <B>backup</B> reference page.
227 </B><DD>Prints the online help for this command. All other valid options
230 <P><STRONG>Output</STRONG>
231 <P>If the <B>-n</B> flag is not provided, the command displays a unique
232 task ID number for the operation, in two places:
234 <P><LI>In the shell window, directly following the command line
235 <P><LI>In the Tape Coordinator window, if the <B>butc</B> process was started
238 <P>The task ID number is not the same as the job ID number displayed by the
239 <B>(backup) jobs</B> command when the <B>(backup) volsetrestore</B>
240 command is issued in interactive mode. The Backup System does not
241 assign either type of ID number until the restoration process actually
243 <P>When the <B>-n</B> flag is included, no task ID or job ID numbers are
244 reported because none are assigned. Instead, the output begins with a
245 count of the number of volumes to be restored, followed by a line for each
246 dump of a volume. For each volume, the line representing the most
247 recent full dump appears first, and lines for any subsequent incremental dumps
248 follow, ordered by dump level. The lines for a given volume do not
249 necessarily appear all together, however.
250 <P>The format of each line is as follows (the output is shown here on two
251 lines only for legibility reasons):
252 <PRE> <VAR>machine partition volume_dumped</VAR> # as <VAR>volume_restored</VAR>; <VAR>tape_name</VAR> (<VAR>tape_ID</VAR>); \
253 pos <VAR>position_number</VAR>; <VAR>date</VAR>
258 <P><DT><B><VAR>machine</VAR>
259 </B><DD>Names the file server machine that currently houses the volume, as listed
261 <P><DT><B><VAR>partition</VAR>
262 </B><DD>Names the partition that currently houses the volume, as listed in the
264 <P><DT><B><VAR>volume_dumped</VAR>
265 </B><DD>Specifies the version (read/write or backup) of the volume that was
266 dumped, as listed in the Backup Database.
267 <P><DT><B><VAR>volume_restored</VAR>
268 </B><DD>Specifies the name under which to restore the volume. The Backup
269 System only restores data to read/write volumes. If the
270 <B>-extension</B> argument is included, then the specified extension
271 appears on the name in this field (for example,
272 <TT>user.pat.rst</TT>).
273 <P><DT><B><VAR>tape_name</VAR>
274 </B><DD>Names the tape containing the dump of the volume, from the Backup
275 Database. If the tape has a permanent name, it appears here;
276 otherwise, it is the AFS tape name.
277 <P><DT><B><VAR>tape_ID</VAR>
278 </B><DD>The tape ID of the tape containing the dump of the volume, from the Backup
280 <P><DT><B><VAR>position_number</VAR>
281 </B><DD>Specifies the dump's position on the tape (for example, <TT>31</TT>
282 indicates that 30 volume dumps precede the current one on the tape). If
283 the dump was written to a backup data file, this number is the ordinal of the
284 16 KB-offset at which the volume's data begins.
285 <P><DT><B><VAR>date</VAR>
286 </B><DD>The date and time when the volume was dumped.
288 <P>One way to generate a file for use as input to the <B>-file</B>
289 argument is to combine the <B>-name</B> and <B>-n</B> options,
290 directing the output to a file. The <I>IBM AFS Administration
291 Guide</I> section on using the Backup System to restore data explains how to
292 edit the file as necessary before using it as input to the <B>-file</B>
294 <P>The output of this command includes only volumes for which the Backup
295 Database includes at least one dump record. The command interpreter
296 generates a message on the standard error stream about volumes that do not
297 have dump records but either are listed in the file named by the
298 <B>-file</B> argument, or appear in the VLDB as a match to a volume entry
299 in the volume set named by the <B>-name</B> argument.
300 <P><STRONG>Examples</STRONG>
301 <P>The following command restores all volumes included in entries in the
302 volume set named <B>data.restore</B>, which was created expressly
303 to restore data to a pair of file server machines on which all data was
304 corrupted due to a software error. All volumes are restored to the
305 sites recorded in their entries in the VLDB.
306 <PRE> % <B>backup volsetrestore -name data.restore</B>
308 backup: task ID of restore operation: 112
309 backup: Finished doing restore
312 <P>The following command restores all volumes that have entries in the file
313 named <B>/tmp/restore</B>:
314 <PRE> % <B>backup volsetrestore -file /tmp/restore</B>
316 backup: task ID of restore operation: 113
317 backup: Finished doing restore
320 <P>The <B>/tmp/restore</B> file has the following contents:
321 <PRE> fs1.abc.com b user.pat
322 fs1.abc.com b user.terry
323 fs1.abc.com b user.smith
324 fs2.abc.com c user.jones
329 <P><STRONG>Privilege Required</STRONG>
330 <P>The issuer must be listed in the <B>/usr/afs/etc/UserList</B> file on
331 every machine where the Backup Server or Volume Location (VL) Server is
332 running, and on every file server machine that houses an affected
333 volume. If the <B>-localauth</B> flag is included, the issuer must
334 instead be logged on to a server machine as the local superuser
336 <P><STRONG>Related Information</STRONG>
337 <P><A HREF="auarf060.htm#HDRBK_INTRO">backup</A>
338 <P><A HREF="auarf063.htm#HDRBK_ADDVOLENTRY">backup addvolentry</A>
339 <P><A HREF="auarf064.htm#HDRBK_ADDVOLSET">backup addvolset</A>
340 <P><A HREF="auarf072.htm#HDRBK_DISKRESTORE">backup diskrestore</A>
341 <P><A HREF="auarf073.htm#HDRBK_DUMP">backup dump</A>
342 <P><A HREF="auarf091.htm#HDRBK_VOLRESTORE">backup volrestore</A>
343 <P><A HREF="auarf126.htm#HDRBUTC">butc</A>
345 <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>
346 <!-- Begin Footer Records ========================================== -->
348 <br>© <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A> All Rights Reserved
350 <!-- End Footer Records ============================================ -->
351 <A NAME="Bot_Of_Page"></A>
git://git.openafs.org / openafs.git / blob