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