3 backup volsetrestore - Restores all volumes in a volume set
7 backup volsetrestore [B<-name> I<volume set name>] [B<-file> I<file name>]
8 [B<-portoffset> I<TC port offset> [I<TC port offset> ...]]
9 [B<-extension> I<new volume name extension>]
10 [B<-n>] [B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
12 backup vols [B<-na> I<volume set name>] [B<-f> I<file name>]
13 [B<-p> I<TC port offset> [I<TC port offset> ...]] [B<-e> I<new volume name extension>]
14 [B<-n>] [B<-l>] [B<-c> I<cell name>] [B<-h>]
18 The C<backup volsetrestore> command restores the complete contents of a
19 group of read/write volumes to the file system, by restoring data from
20 the last full dump and all subsequent incremental dumps of each
21 volume. It is most useful for recovering from loss of data on multiple
22 partitions, since it can restore each of a defined set of volumes to a
25 (If the B<FILE YES> instruction appears in the
26 B</usr/afs/backup/CFG_>I<device_name> file associated with the specified
27 port offset, then the C<backup volsetrestore> command restores data from
28 the backup data file listed for that port offset in the Tape
29 Coordinator's B</usr/afs/backup/tapeconfig> file, instead of from tape.
30 For the sake of clarity, the following text refers to tapes only, but
31 the Backup System handles backup data files in much the same way.)
33 If restoring one or more volumes to a single site only, it is usually
34 more efficient to use the C<backup volrestore> command. If restoring all
35 volumes that resided on a single partition, it is usually more
36 efficient to use the C<backup diskrestore> command.
38 Indicate the volumes to restore by providing either the B<-name> argument
39 or the B<-file> argument:
45 The B<-name> argument names a volume set. The Backup System restores
46 all volumes listed in the Volume Location Database (VLDB) that
47 match the server, partition, and volume name criteria defined in
48 the volume set's volume entries, and for which dumps are
49 available. It restores the volumes to their current site (machine
50 and partition), and by default overwrites the existing volume
53 It is not required that the volume set was previously used to back
54 up volumes (was used as the B<-volumeset> option to the C<backup dump>
55 command). It can be defined especially to match the volumes that
56 need to be restored with this command, and that is usually the
57 better choice. Indeed, a temporary volume set, created by
58 including the B<-temporary> flag to the C<backup addvolset> command, can
59 be especially useful in this context. A temporary volume set is
60 not added to the Backup Database and exists only during the
61 current interactive backup session, which is suitable if the
62 volume set is needed only to complete the single restore operation
63 initialized by this command.
65 The reason that a specially defined volume set is probably better
66 is that volume sets previously defined for use in dump operations
67 usually match the backup version of volumes, whereas for a restore
68 operation it is best to define volume entries that match the base
69 (read/write) name. In that case, the Backup System searches the
70 Backup Database for the newest dump set that includes either the
71 read/write or the backup version of the volume. If, in contrast, a
72 volume entry explicitly matches the volume's backup or read-only
73 version, the Backup System restores dumps of that volume version
78 The B<-file> argument names a file that lists specific volumes and
79 the site to which to restore each. The volume name must match the
80 name used in Backup Database dump records rather than in the VLDB,
81 if they differ, because the Backup System does not look up volumes
82 in the VLDB. The specified site can be different than the volume's
83 current one; in that case, the Backup System removes the current
84 version of the volume and updates the volume's location
85 information in the VLDB.
89 If all of the full and incremental dumps of all relevant volumes were
90 not written to a type of tape that a single Tape Coordinator can read,
91 use the B<-portoffset> argument to list multiple port offset numbers in
92 the order in which the tapes are needed (first list the port offset
93 for the full dump, second the port offset for the level 1 incremental
94 dump, and so on). This implies that the full dumps of all relevant
95 volumes must have been written to a type of tape that the first Tape
96 Coordinator can read, the level 1 incremental dumps to a type of tape
97 the second Tape Coordinator can read, and so on. If dumps are on
98 multiple incompatible tape types, use the C<backup volrestore> command to
99 restore individual volumes, or use this command after defining new
100 volume sets that group together volumes that were dumped to compatible
101 tape types. For further discussion, see the IBM AFS Administration
104 By default, the Backup System overwrites the contents of an existing
105 volume with the restored data. To create a new volume to house the
106 restored version instead, use the B<-extension> argument. The Backup
107 System derives the new volume's name by adding the specified extension
108 to the read/write base name, and creates a new VLDB entry. The command
109 does not affect the existing volume in any way. However, if a volume
110 with the specified extension also already exists, the command
113 The B<-n> flag produces a list of the volumes to be restored if the B<-n>
114 flag were not included, without actually restoring any volumes. See
115 the L</"OUTPUT"> section of this reference page for a detailed description
116 of the output, and suggestions on how to combine it most effectively
117 with the B<-file> and B<-name> arguments.
119 The execution time for a C<backup volsetrestore> command depends on the
120 number of volumes to be restored and the amount of data in them, but
121 it can take hours to restore a large number of volumes. One way to
122 reduce the time is to run multiple instances of the command
123 simultaneously, either using the B<-name> argument to specify disjoint
124 volume sets for each command, or the B<-file> argument to name files that
125 list different volumes. This is possible if there are multiple
126 available Tape Coordinators that can read the required tapes.
127 Depending on how the volumes to be restored were dumped to tape,
128 specifying disjoint volume sets can also reduce the number of tape
131 The Tape Coordinator's default response to this command is to access
132 the first tape it needs by invoking the B<MOUNT> instruction in the local
133 B</usr/afs/backup/CFG_>I<device_name> file, or by prompting the backup
134 operator to insert the tape if there is no B<MOUNT> instruction. However,
135 if the B<AUTOQUERY NO> instruction appears in the B<CFG_>I<device_name> file,
136 or if the issuer of the B<butc> command included the B<-noautoquery> flag,
137 the Tape Coordinator instead expects the tape to be in the device
138 already. If it is not, or is the wrong tape, the Tape Coordinator
139 invokes the B<MOUNT> instruction or prompts the operator. It also invokes
140 the B<MOUNT> instruction or prompts for any additional tapes needed to
141 complete the restore operation; the backup operator must arrange to
148 =item B<-name> I<volume set name>
150 Names a volume set to restore. The Backup System restores all
151 of the volumes listed in the VLDB that match the volume set's
152 volume entries. Provide this argument or the B<-file> argument,
155 =item B<-file> I<file name>
157 Specifies the full pathname of a file that lists one or more
158 volumes and the site (file server machine and partition) to
159 which to restore each. Use either this argument or the B<-name>
160 argument, but not both.
162 Each volume's entry must appear on its own (unbroken) line in
163 the file, and have the following format:
174 Names the file server machine to which to restore the
179 Names the partition to which to restore the volume.
183 Names the volume to restore. It is generally best to
184 specify the base (read/write) name of each volume. In
185 this case, the Backup System searches the Backup Database
186 for the newest dump set that includes a dump of either
187 the read/write or the backup version of the volume. It
188 restores the dumps of that version of the volume,
189 starting with the most recent full dump. If, in contrast,
190 the name explicitly includes the B<.backup> or B<.readonly>
191 extension, the Backup System restores dumps of that
196 Is any other text. The Backup System ignores any text on
197 each line that appears after the volume name, so this
198 field can be used for notes helpful to the backup
199 operator or other administrator.
203 Do not use wildcards (for example, B<.*>) in the I<machine>,
204 I<partition>, or I<volume> fields. It is acceptable for multiple
205 lines in the file to name the same volume, but the Backup
206 System processes only the first of them.
208 =item B<-extension> I<new volume name extension>
210 Creates a new volume for each volume specified by the B<-name> or
211 B<-file> argument, to house the restored data from that volume.
212 The Backup System derives the new volume's name by appending
213 the specified string to the read/write base name, and creates a
214 new VLDB volume entry. It preserves the contents of each
215 existing volume. Any string other than B<.readonly> or B<.backup> is
216 acceptable, but the combination of the base name and extension
217 cannot exceed 22 characters in length. To use a period to
218 separate the extension from the name, specify it as the first
219 character of the string (as in B<.rst>, for example).
221 =item B<-portoffset> I<TC port offset> [I<TC port offset> ...]
223 Specifies one or more port offset numbers (up to a maximum of
224 128), each corresponding to a Tape Coordinator to use in the
225 operation. If there is more than one value, the Backup System
226 uses the first one when restoring the full dump of each volume,
227 the second one when restoring the level 1 incremental dump of
228 each volume, and so on. It uses the final value in the list
229 when restoring dumps at the corresponding depth in the dump
230 hierarchy and all dumps at lower levels.
232 Provide this argument unless the default value of 0 (zero) is
233 appropriate for all dumps. If B<0> is just one of the values in
234 the list, provide it explicitly in the appropriate order.
238 Displays a list of the volumes to be restored if the flag were
239 not included, without actually restoring them. The L</"OUTPUT">
240 section of this reference page details the format of the
241 output. When combined with the B<-name> argument, its output is
242 easily edited for use as input to the B<-file> argument on a
243 subsequent C<backup volsetrestore> command.
247 Constructs a server ticket using a key from the local
248 B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
249 presents it to the Backup Server, Volume Server and VL Server
250 during mutual authentication. Do not combine this flag with the
251 B<-cell> argument. For more details, see the introductory L<backup(1)>
254 =item B<-cell> I<cell name>
256 Names the cell in which to run the command. Do not combine this
257 argument with the B<-localauth> flag. For more details, see the
258 introductory L<backup(1)> reference page.
262 Prints the online help for this command. All other valid
269 If the B<-n> flag is not provided, the command displays a unique task ID
270 number for the operation, in two places:
276 In the shell window, directly following the command line
280 In the Tape Coordinator window, if the B<butc> process was started at
285 The task ID number is not the same as the job ID number displayed by
286 the C<(backup) jobs> command when the C<(backup) volsetrestore> command is
287 issued in interactive mode. The Backup System does not assign either
288 type of ID number until the restoration process actually begins.
290 When the B<-n> flag is included, no task ID or job ID numbers are
291 reported because none are assigned. Instead, the output begins with a
292 count of the number of volumes to be restored, followed by a line for
293 each dump of a volume. For each volume, the line representing the most
294 recent full dump appears first, and lines for any subsequent
295 incremental dumps follow, ordered by dump level. The lines for a given
296 volume do not necessarily appear all together, however.
298 The format of each line is as follows (the output is shown here on two
299 lines only for legibility reasons):
301 machine partition volume_dumped # as volume_restored; tape_name (tape_ID); \
302 pos position_number; date
310 Names the file server machine that currently houses the volume,
311 as listed in the VLDB.
315 Names the partition that currently houses the volume, as listed
318 =item B<volume_dumped>
320 Specifies the version (read/write or backup) of the volume that
321 was dumped, as listed in the Backup Database.
323 =item B<volume_restored>
325 Specifies the name under which to restore the volume. The
326 Backup System only restores data to read/write volumes. If the
327 B<-extension> argument is included, then the specified extension
328 appears on the name in this field (for example, C<user.pat.rst>).
332 Names the tape containing the dump of the volume, from the
333 Backup Database. If the tape has a permanent name, it appears
334 here; otherwise, it is the AFS tape name.
338 The tape ID of the tape containing the dump of the volume, from
341 =item B<position_number>
343 Specifies the dump's position on the tape (for example, C<31>
344 indicates that 30 volume dumps precede the current one on the
345 tape). If the dump was written to a backup data file, this
346 number is the ordinal of the 16 KB-offset at which the volume's
351 The date and time when the volume was dumped.
355 One way to generate a file for use as input to the B<-file> argument is
356 to combine the B<-name> and B<-n> options, directing the output to a file.
357 The IBM AFS Administration Guide section on using the Backup System to
358 restore data explains how to edit the file as necessary before using
359 it as input to the B<-file> argument.
361 The output of this command includes only volumes for which the Backup
362 Database includes at least one dump record. The command interpreter
363 generates a message on the standard error stream about volumes that do
364 not have dump records but either are listed in the file named by the
365 B<-file> argument, or appear in the VLDB as a match to a volume entry in
366 the volume set named by the B<-name> argument.
370 The following command restores all volumes included in entries in the
371 volume set named B<data.restore>, which was created expressly to restore
372 data to a pair of file server machines on which all data was corrupted
373 due to a software error. All volumes are restored to the sites
374 recorded in their entries in the VLDB.
376 backup volsetrestore -name data.restore
378 backup: task ID of restore operation: 112
379 backup: Finished doing restore
381 The following command restores all volumes that have entries in the
382 file named B</tmp/restore>:
384 backup volsetrestore -file B</tmp/restore>
386 backup: task ID of restore operation: 113
387 backup: Finished doing restore
389 The B</tmp/restore> file has the following contents:
391 fs1.abc.com b user.pat
392 fs1.abc.com b user.terry
393 fs1.abc.com b user.smith
394 fs2.abc.com c user.jones
398 =head1 PRIVILEGE REQUIRED
400 The issuer must be listed in the B</usr/afs/etc/UserList> file on every
401 machine where the Backup Server or Volume Location (VL) Server is
402 running, and on every file server machine that houses an affected
403 volume. If the B<-localauth> flag is included, the issuer must instead be
404 logged on to a server machine as the local superuser B<root>.
408 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
410 Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
411 and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
412 Stanford Linear Accelerator Center, a department of Stanford University.
417 L<backup_addvolentry(1)>,
418 L<backup_addvolset(1)>,
419 L<backup_diskrestore(1)>,
421 L<backup_volrestore(1)>,