Update backup suite manpages
[openafs.git] / doc / man-pages / pod8 / backup_volsetrestore.pod
1 =head1 NAME
2
3 backup_volsetrestore - Restores all volumes in a volume set
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<backup volsetrestore> S<<< [B<-name> <I<volume set name>>] >>>
11     S<<< [B<-file> <I<file name>>] >>>
12     S<<< [B<-portoffset> <I<TC port offset>>+] >>>
13     S<<< [B<-extension> <I<new volume name extension>>] >>> [B<-n>]
14     [B<-localauth>] S<<< [B<-cell> <I<cell name>>] >>> [B<-help>]
15
16 B<backup vols> S<<< [B<-na> <I<volume set name>>] >>>
17     S<<< [B<-f> <I<file name>>] >>>
18     S<<< [B<-p> <I<TC port offset>>+] >>>
19     S<<< [B<-e> <I<new volume name extension>>] >>>
20     [B<-n>] [B<-l>] S<<< [B<-c> <I<cell name>>] >>> [B<-h>]
21
22 =for html
23 </div>
24
25 =head1 DESCRIPTION
26
27 The B<backup volsetrestore> command restores the complete contents of a
28 group of read/write volumes to the file system, by restoring data from the
29 last full dump and all subsequent incremental dumps of each volume.  It is
30 most useful for recovering from loss of data on multiple partitions, since
31 it can restore each of a defined set of volumes to a different site.
32
33 (If the C<FILE YES> instruction appears in the
34 F</usr/afs/backup/CFG_I<device_name>> file associated with the specified
35 port offset, then the B<backup volsetrestore> command restores data from
36 the backup data file listed for that port offset in the Tape Coordinator's
37 F</usr/afs/backup/tapeconfig> file, instead of from tape. For the sake of
38 clarity, the following text refers to tapes only, but the Backup System
39 handles backup data files in much the same way.)
40
41 If restoring one or more volumes to a single site only, it is usually more
42 efficient to use the B<backup volrestore> command. If restoring all
43 volumes that resided on a single partition, it is usually more efficient
44 to use the B<backup diskrestore> command.
45
46 Indicate the volumes to restore by providing either the B<-name> argument
47 or the B<-file> argument:
48
49 =over 4
50
51 =item *
52
53 The B<-name> argument names a volume set. The Backup System restores all
54 volumes listed in the Volume Location Database (VLDB) that match the
55 server, partition, and volume name criteria defined in the volume set's
56 volume entries, and for which dumps are available. It restores the volumes
57 to their current site (machine and partition), and by default overwrites
58 the existing volume contents.
59
60 It is not required that the volume set was previously used to back up
61 volumes (was used as the B<-volumeset> option to the B<backup dump>
62 command). It can be defined especially to match the volumes that need to
63 be restored with this command, and that is usually the better
64 choice. Indeed, a I<temporary> volume set, created by including the
65 B<-temporary> flag to the B<backup addvolset> command, can be especially
66 useful in this context. A temporary volume set is not added to the Backup
67 Database and exists only during the current interactive backup session,
68 which is suitable if the volume set is needed only to complete the single
69 restore operation initialized by this command.
70
71 The reason that a specially defined volume set is probably better is that
72 volume sets previously defined for use in dump operations usually match
73 the backup version of volumes, whereas for a restore operation it is best
74 to define volume entries that match the base (read/write) name. In that
75 case, the Backup System searches the Backup Database for the newest dump
76 set that includes either the read/write or the backup version of the
77 volume. If, in contrast, a volume entry explicitly matches the volume's
78 backup or read-only version, the Backup System restores dumps of that
79 volume version only.
80
81 =item *
82
83 The B<-file> argument names a file that lists specific volumes and the
84 site to which to restore each. The volume name must match the name used in
85 Backup Database dump records rather than in the VLDB, if they differ,
86 because the Backup System does not look up volumes in the VLDB. The
87 specified site can be different than the volume's current one; in that
88 case, the Backup System removes the current version of the volume and
89 updates the volume's location information in the VLDB.
90
91 =back
92
93 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> argument to list multiple port offset numbers in the order
96 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,
100 the level 1 incremental dumps to a type of tape the second Tape
101 Coordinator can read, and so on. If dumps are on multiple incompatible
102 tape types, use the B<backup volrestore> command to restore individual
103 volumes, or use this command after defining new volume sets that group
104 together volumes that were dumped to compatible tape types. For further
105 discussion, see the I<IBM AFS Administration Guide>.
106
107 By default, the Backup System overwrites the contents of an existing
108 volume with the restored data. To create a new volume to house the
109 restored version instead, use the B<-extension> argument. The Backup
110 System derives the new volume's name by adding the specified extension to
111 the read/write base name, and creates a new VLDB entry. The command does
112 not affect the existing volume in any way. However, if a volume with the
113 specified extension also already exists, the command overwrites it.
114
115 The B<-n> flag produces a list of the volumes to be restored if the B<-n>
116 flag were not included, without actually restoring any volumes. See
117 L<OUTPUT> for a detailed description of the output, and suggestions on how
118 to combine it most effectively with the B<-file> and B<-name> arguments.
119
120 The execution time for a B<backup volsetrestore> command depends on the
121 number of volumes to be restored and the amount of data in them, but it
122 can take hours to restore a large number of volumes. One way to reduce the
123 time is to run multiple instances of the command simultaneously, either
124 using the B<-name> argument to specify disjoint volume sets for each
125 command, or the B<-file> argument to name files that list different
126 volumes. This is possible if there are multiple available Tape
127 Coordinators that can read the required tapes. Depending on how the
128 volumes to be restored were dumped to tape, specifying disjoint volume
129 sets can also reduce the number of tape changes required.
130
131 The Tape Coordinator's default response to this command is to access the
132 first tape it needs by invoking the C<MOUNT> instruction in the local
133 F</usr/afs/backup/CFG_I<device_name>> file, or by prompting the backup
134 operator to insert the tape if there is no C<MOUNT> instruction. However,
135 if the C<AUTOQUERY NO> instruction appears in the F<CFG_I<device_name>>
136 file, or if the issuer of the B<butc> command included the B<-noautoquery>
137 flag, 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 invokes
139 the C<MOUNT> instruction or prompts the operator. It also invokes the
140 C<MOUNT> instruction or prompts for any additional tapes needed to
141 complete the restore operation; the backup operator must arrange to
142 provide them.
143
144 =head1 OPTIONS
145
146 =over 4
147
148 =item B<-name> <I<volume set name>>
149
150 Names a volume set to restore. The Backup System restores all of the
151 volumes listed in the VLDB that match the volume set's volume
152 entries. Provide this argument or the B<-file> argument, but not both.
153
154 =item B<-file> <I<file name>>
155
156 Specifies the full pathname of a file that lists one or more volumes and
157 the site (file server machine and partition) to which to restore each.
158 Use either this argument or the B<-name> argument, but not both.
159
160 Each volume's entry must appear on its own (unbroken) line in the file,
161 and have the following format:
162
163     <machine> <partition> <volume> [<comments> ...]
164
165 where
166
167 =over 4
168
169 =item <machine>
170
171 Names the file server machine to which to restore the volume.
172
173 =item <partition>
174
175 Names the partition to which to restore the volume.
176
177 =item <volume>
178
179 Names the volume to restore. It is generally best to specify the base
180 (read/write) name of each volume. In this case, the Backup System searches
181 the Backup Database for the newest dump set that includes a dump of either
182 the read/write or the backup version of the volume. It restores the dumps
183 of that version of the volume, starting with the most recent full
184 dump. If, in contrast, the name explicitly includes the C<.backup> or
185 C<.readonly> extension, the Backup System restores dumps of that volume
186 version only.
187
188 =item <comments> ...
189
190 Is any other text. The Backup System ignores any text on each line that
191 appears after the volume name, so this field can be used for notes helpful
192 to the backup operator or other administrator.
193
194 =back
195
196 Do not use wildcards (for example, C<.*>) in the <machine>, <partition>,
197 or <volume> fields. It is acceptable for multiple lines in the file to
198 name the same volume, but the Backup System processes only the first of
199 them.
200
201 =item B<-extension> <I<new volume name extension>>
202
203 Creates a new volume for each volume specified by the B<-name> or B<-file>
204 argument, to house the restored data from that volume.  The Backup System
205 derives the new volume's name by appending the specified string to the
206 read/write base name, and creates a new VLDB volume entry. It preserves
207 the contents of each existing volume. Any string other than C<.readonly>
208 or C<.backup> is acceptable, but the combination of the base name and
209 extension cannot exceed 22 characters in length. To use a period to
210 separate the extension from the name, specify it as the first character of
211 the string (as in C<.rst>, for example).
212
213 =item B<-portoffset> <I<TC port offset>>+
214
215 Specifies one or more port offset numbers (up to a maximum of 128), each
216 corresponding to a Tape Coordinator to use in the operation. If there is
217 more than one value, the Backup System uses the first one when restoring
218 the full dump of each volume, the second one when restoring the level 1
219 incremental dump of each volume, and so on. It uses the final value in the
220 list when restoring dumps at the corresponding depth in the dump hierarchy
221 and all dumps at lower levels.
222
223 Provide this argument unless the default value of 0 (zero) is appropriate
224 for all dumps. If C<0> is just one of the values in the list, provide it
225 explicitly in the appropriate order.
226
227 =item B<-n>
228
229 Displays a list of the volumes to be restored if the flag were not
230 included, without actually restoring them. L<OUTPUT> details the format of
231 the output. When combined with the B<-name> argument, its output is easily
232 edited for use as input to the B<-file> argument on a subsequent B<backup
233 volsetrestore> command.
234
235 =item B<-localauth>
236
237 Constructs a server ticket using a key from the local
238 F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
239 it to the Backup Server, Volume Server and VL Server during mutual
240 authentication. Do not combine this flag with the B<-cell> argument. For
241 more details, see L<backup(8)>.
242
243 =item B<-cell> <I<cell name>>
244
245 Names the cell in which to run the command. Do not combine this argument
246 with the B<-localauth> flag. For more details, see L<backup(8)>.
247
248 =item B<-help>
249
250 Prints the online help for this command. All other valid options are
251 ignored.
252
253 =back
254
255 =head1 OUTPUT
256
257 If the B<-n> flag is not provided, the command displays a unique task ID
258 number for the operation, in two places:
259
260 =over 4
261
262 =item *
263
264 In the shell window, directly following the command line.
265
266 =item *
267
268 In the Tape Coordinator window, if the butc process was started at debug
269 level 1.
270
271 =back
272
273 The task ID number is not the same as the job ID number displayed by the
274 B<backup jobs> command when the B<backup volsetrestore> command is issued
275 in interactive mode. The Backup System does not assign either type of ID
276 number until the restoration process actually begins.
277
278 When the B<-n> flag is included, no task ID or job ID numbers are reported
279 because none are assigned. Instead, the output begins with a count of the
280 number of volumes to be restored, followed by a line for each dump of a
281 volume. For each volume, the line representing the most recent full dump
282 appears first, and lines for any subsequent incremental dumps follow,
283 ordered by dump level. The lines for a given volume do not necessarily
284 appear all together, however.
285
286 The format of each line is as follows (the output is shown here on two
287 lines only for legibility reasons):
288
289    <machine> <partition> <volume_dumped> # as <volume_restored>; \
290        <tape_name> (<tape_ID>); pos <position_number>; <date>
291
292 where
293
294 =over 4
295
296 =item <machine>
297
298 Names the file server machine that currently houses the volume, as listed
299 in the VLDB.
300
301 =item <partition>
302
303 Names the partition that currently houses the volume, as listed in the
304 VLDB.
305
306 =item <volume_dumped>
307
308 Specifies the version (read/write or backup) of the volume that was
309 dumped, as listed in the Backup Database.
310
311 =item <volume_restored>
312
313 Specifies the name under which to restore the volume. The Backup System
314 only restores data to read/write volumes. If the B<-extension> argument is
315 included, then the specified extension appears on the name in this field
316 (for example, C<user.pat.rst>).
317
318 =item <tape_name>
319
320 Names the tape containing the dump of the volume, from the Backup
321 Database. If the tape has a permanent name, it appears here; otherwise, it
322 is the AFS tape name.
323
324 =item <tape_ID>
325
326 The tape ID of the tape containing the dump of the volume, from the Backup
327 Database.
328
329 =item <position_number>
330
331 Specifies the dump's position on the tape (for example, C<31> indicates
332 that 30 volume dumps precede the current one on the tape). If the dump was
333 written to a backup data file, this number is the ordinal of the 16
334 KB-offset at which the volume's data begins.
335
336 =item <date>
337
338 The date and time when the volume was dumped.
339
340 =back
341
342 One way to generate a file for use as input to the B<-file> argument is to
343 combine the B<-name> and B<-n> options, directing the output to a
344 file. The I<IBM AFS Administration Guide> section on using the Backup
345 System to restore data explains how to edit the file as necessary before
346 using it as input to the B<-file> argument.
347
348 The output of this command includes only volumes for which the Backup
349 Database includes at least one dump record. The command interpreter
350 generates a message on the standard error stream about volumes that do not
351 have dump records but either are listed in the file named by the B<-file>
352 argument, or appear in the VLDB as a match to a volume entry in the volume
353 set named by the B<-name> argument.
354
355 =head1 EXAMPLES
356
357 The following command restores all volumes included in entries in the
358 volume set named C<data.restore>, which was created expressly to restore
359 data to a pair of file server machines on which all data was corrupted due
360 to a software error. All volumes are restored to the sites recorded in
361 their entries in the VLDB.
362
363    % backup volsetrestore -name data.restore
364    Starting restore
365    backup: task ID of restore operation: 112
366    backup: Finished doing restore
367
368 The following command restores all volumes that have entries in the file
369 named F</tmp/restore>:
370
371    % backup volsetrestore -file /tmp/restore
372    Starting restore
373    backup: task ID of restore operation: 113
374    backup: Finished doing restore
375
376 The F</tmp/restore> file has the following contents:
377
378    fs1.abc.com b user.pat
379    fs1.abc.com b user.terry
380    fs1.abc.com b user.smith
381    fs2.abc.com c user.jones
382           .         .     .
383           .         .     .
384
385 =head1 PRIVILEGE REQUIRED
386
387 The issuer must be listed in the F</usr/afs/etc/UserList> file on every
388 machine where the Backup Server or Volume Location (VL) Server is running,
389 and on every file server machine that houses an affected volume. If the
390 B<-localauth> flag is included, the issuer must instead be logged on to a
391 server machine as the local superuser C<root>.
392
393 =head1 SEE ALSO
394
395 L<butc(5)>,
396 L<backup(8)>,
397 L<backup_addvolentry(8)>,
398 L<backup_addvolset(8)>,
399 L<backup_diskrestore(8)>,
400 L<backup_dump(8)>,
401 L<backup_volrestore(8)>,
402 L<butc(8)>
403
404 =head1 COPYRIGHT
405
406 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
407
408 This documentation is covered by the IBM Public License Version 1.0.  It was
409 converted from HTML to POD by software written by Chas Williams and Russ
410 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.