Commit | Line | Data |
---|---|---|
805e021f CE |
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<-dryrun> | 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<-dryrun> | 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<OpenAFS 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<-dryrun> flag produces a list of the volumes to be restored if the | |
116 | B<-dryrun> flag were not included, without actually restoring any volumes. | |
117 | See L</OUTPUT> for a detailed description of the output, and suggestions | |
118 | on how to combine it most effectively with the B<-file> and B<-name> | |
119 | arguments. | |
120 | ||
121 | The execution time for a B<backup volsetrestore> command depends on the | |
122 | number of volumes to be restored and the amount of data in them, but it | |
123 | can take hours to restore a large number of volumes. One way to reduce the | |
124 | time is to run multiple instances of the command simultaneously, either | |
125 | using the B<-name> argument to specify disjoint volume sets for each | |
126 | command, or the B<-file> argument to name files that list different | |
127 | volumes. This is possible if there are multiple available Tape | |
128 | Coordinators that can read the required tapes. Depending on how the | |
129 | volumes to be restored were dumped to tape, specifying disjoint volume | |
130 | sets can also reduce the number of tape changes required. | |
131 | ||
132 | The Tape Coordinator's default response to this command is to access the | |
133 | first tape it needs by invoking the C<MOUNT> instruction in the local | |
134 | F</usr/afs/backup/CFG_I<device_name>> file, or by prompting the backup | |
135 | operator to insert the tape if there is no C<MOUNT> instruction. However, | |
136 | if the C<AUTOQUERY NO> instruction appears in the F<CFG_I<device_name>> | |
137 | file, or if the issuer of the B<butc> command included the B<-noautoquery> | |
138 | flag, the Tape Coordinator instead expects the tape to be in the device | |
139 | already. If it is not, or is the wrong tape, the Tape Coordinator invokes | |
140 | the C<MOUNT> instruction or prompts the operator. It also invokes the | |
141 | C<MOUNT> instruction or prompts for any additional tapes needed to | |
142 | complete the restore operation; the backup operator must arrange to | |
143 | provide them. | |
144 | ||
145 | =head1 OPTIONS | |
146 | ||
147 | =over 4 | |
148 | ||
149 | =item B<-name> <I<volume set name>> | |
150 | ||
151 | Names a volume set to restore. The Backup System restores all of the | |
152 | volumes listed in the VLDB that match the volume set's volume | |
153 | entries. Provide this argument or the B<-file> argument, but not both. | |
154 | ||
155 | =item B<-file> <I<file name>> | |
156 | ||
157 | Specifies the full pathname of a file that lists one or more volumes and | |
158 | the site (file server machine and partition) to which to restore each. | |
159 | Use either this argument or the B<-name> argument, but not both. | |
160 | ||
161 | Each volume's entry must appear on its own (unbroken) line in the file, | |
162 | and have the following format: | |
163 | ||
164 | <machine> <partition> <volume> [<comments> ...] | |
165 | ||
166 | where | |
167 | ||
168 | =over 4 | |
169 | ||
170 | =item <machine> | |
171 | ||
172 | Names the file server machine to which to restore the volume. | |
173 | ||
174 | =item <partition> | |
175 | ||
176 | Names the partition to which to restore the volume. | |
177 | ||
178 | =item <volume> | |
179 | ||
180 | Names the volume to restore. It is generally best to specify the base | |
181 | (read/write) name of each volume. In this case, the Backup System searches | |
182 | the Backup Database for the newest dump set that includes a dump of either | |
183 | the read/write or the backup version of the volume. It restores the dumps | |
184 | of that version of the volume, starting with the most recent full | |
185 | dump. If, in contrast, the name explicitly includes the C<.backup> or | |
186 | C<.readonly> extension, the Backup System restores dumps of that volume | |
187 | version only. | |
188 | ||
189 | =item <comments> ... | |
190 | ||
191 | Is any other text. The Backup System ignores any text on each line that | |
192 | appears after the volume name, so this field can be used for notes helpful | |
193 | to the backup operator or other administrator. | |
194 | ||
195 | =back | |
196 | ||
197 | Do not use wildcards (for example, C<.*>) in the <machine>, <partition>, | |
198 | or <volume> fields. It is acceptable for multiple lines in the file to | |
199 | name the same volume, but the Backup System processes only the first of | |
200 | them. | |
201 | ||
202 | =item B<-extension> <I<new volume name extension>> | |
203 | ||
204 | Creates a new volume for each volume specified by the B<-name> or B<-file> | |
205 | argument, to house the restored data from that volume. The Backup System | |
206 | derives the new volume's name by appending the specified string to the | |
207 | read/write base name, and creates a new VLDB volume entry. It preserves | |
208 | the contents of each existing volume. Any string other than C<.readonly> | |
209 | or C<.backup> is acceptable, but the combination of the base name and | |
210 | extension cannot exceed 22 characters in length. To use a period to | |
211 | separate the extension from the name, specify it as the first character of | |
212 | the string (as in C<.rst>, for example). | |
213 | ||
214 | =item B<-portoffset> <I<TC port offset>>+ | |
215 | ||
216 | Specifies one or more port offset numbers (up to a maximum of 128), each | |
217 | corresponding to a Tape Coordinator to use in the operation. If there is | |
218 | more than one value, the Backup System uses the first one when restoring | |
219 | the full dump of each volume, the second one when restoring the level 1 | |
220 | incremental dump of each volume, and so on. It uses the final value in the | |
221 | list when restoring dumps at the corresponding depth in the dump hierarchy | |
222 | and all dumps at lower levels. | |
223 | ||
224 | Provide this argument unless the default value of 0 (zero) is appropriate | |
225 | for all dumps. If C<0> is just one of the values in the list, provide it | |
226 | explicitly in the appropriate order. | |
227 | ||
228 | =item B<-dryrun> | B<-n> | |
229 | ||
230 | Displays a list of the volumes to be restored if the flag were not | |
231 | included, without actually restoring them. L</OUTPUT> details the format of | |
232 | the output. When combined with the B<-name> argument, its output is easily | |
233 | edited for use as input to the B<-file> argument on a subsequent B<backup | |
234 | volsetrestore> command. | |
235 | ||
236 | =item B<-localauth> | |
237 | ||
238 | Constructs a server ticket using a key from the local | |
239 | F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents | |
240 | it to the Backup Server, Volume Server and VL Server during mutual | |
241 | authentication. Do not combine this flag with the B<-cell> argument. For | |
242 | more details, see L<backup(8)>. | |
243 | ||
244 | =item B<-cell> <I<cell name>> | |
245 | ||
246 | Names the cell in which to run the command. Do not combine this argument | |
247 | with the B<-localauth> flag. For more details, see L<backup(8)>. | |
248 | ||
249 | =item B<-help> | |
250 | ||
251 | Prints the online help for this command. All other valid options are | |
252 | ignored. | |
253 | ||
254 | =back | |
255 | ||
256 | =head1 OUTPUT | |
257 | ||
258 | If the B<-dryrun> flag is not provided, the command displays a unique | |
259 | task ID number for the operation, in two places: | |
260 | ||
261 | =over 4 | |
262 | ||
263 | =item * | |
264 | ||
265 | In the shell window, directly following the command line. | |
266 | ||
267 | =item * | |
268 | ||
269 | In the Tape Coordinator window, if the butc process was started at debug | |
270 | level 1. | |
271 | ||
272 | =back | |
273 | ||
274 | The task ID number is not the same as the job ID number displayed by the | |
275 | B<backup jobs> command when the B<backup volsetrestore> command is issued | |
276 | in interactive mode. The Backup System does not assign either type of ID | |
277 | number until the restoration process actually begins. | |
278 | ||
279 | When the B<-dryrun> flag is included, no task ID or job ID numbers are | |
280 | reported because none are assigned. Instead, the output begins with a | |
281 | count of the number of volumes to be restored, followed by a line for | |
282 | each dump of a volume. For each volume, the line representing the most | |
283 | recent full dump appears first, and lines for any subsequent incremental | |
284 | dumps follow, ordered by dump level. The lines for a given volume do not | |
285 | necessarily appear all together, however. | |
286 | ||
287 | The format of each line is as follows (the output is shown here on two | |
288 | lines only for legibility reasons): | |
289 | ||
290 | <machine> <partition> <volume_dumped> # as <volume_restored>; \ | |
291 | <tape_name> (<tape_ID>); pos <position_number>; <date> | |
292 | ||
293 | where | |
294 | ||
295 | =over 4 | |
296 | ||
297 | =item <machine> | |
298 | ||
299 | Names the file server machine that currently houses the volume, as listed | |
300 | in the VLDB. | |
301 | ||
302 | =item <partition> | |
303 | ||
304 | Names the partition that currently houses the volume, as listed in the | |
305 | VLDB. | |
306 | ||
307 | =item <volume_dumped> | |
308 | ||
309 | Specifies the version (read/write or backup) of the volume that was | |
310 | dumped, as listed in the Backup Database. | |
311 | ||
312 | =item <volume_restored> | |
313 | ||
314 | Specifies the name under which to restore the volume. The Backup System | |
315 | only restores data to read/write volumes. If the B<-extension> argument is | |
316 | included, then the specified extension appears on the name in this field | |
317 | (for example, C<user.pat.rst>). | |
318 | ||
319 | =item <tape_name> | |
320 | ||
321 | Names the tape containing the dump of the volume, from the Backup | |
322 | Database. If the tape has a permanent name, it appears here; otherwise, it | |
323 | is the AFS tape name. | |
324 | ||
325 | =item <tape_ID> | |
326 | ||
327 | The tape ID of the tape containing the dump of the volume, from the Backup | |
328 | Database. | |
329 | ||
330 | =item <position_number> | |
331 | ||
332 | Specifies the dump's position on the tape (for example, C<31> indicates | |
333 | that 30 volume dumps precede the current one on the tape). If the dump was | |
334 | written to a backup data file, this number is the ordinal of the 16 | |
335 | KB-offset at which the volume's data begins. | |
336 | ||
337 | =item <date> | |
338 | ||
339 | The date and time when the volume was dumped. | |
340 | ||
341 | =back | |
342 | ||
343 | One way to generate a file for use as input to the B<-file> argument is to | |
344 | combine the B<-name> and B<-dryrun> options, directing the output to a | |
345 | file. The I<OpenAFS Administration Guide> section on using the Backup | |
346 | System to restore data explains how to edit the file as necessary before | |
347 | using it as input to the B<-file> argument. | |
348 | ||
349 | The output of this command includes only volumes for which the Backup | |
350 | Database includes at least one dump record. The command interpreter | |
351 | generates a message on the standard error stream about volumes that do not | |
352 | have dump records but either are listed in the file named by the B<-file> | |
353 | argument, or appear in the VLDB as a match to a volume entry in the volume | |
354 | set named by the B<-name> argument. | |
355 | ||
356 | =head1 EXAMPLES | |
357 | ||
358 | The following command restores all volumes included in entries in the | |
359 | volume set named C<data.restore>, which was created expressly to restore | |
360 | data to a pair of file server machines on which all data was corrupted due | |
361 | to a software error. All volumes are restored to the sites recorded in | |
362 | their entries in the VLDB. | |
363 | ||
364 | % backup volsetrestore -name data.restore | |
365 | Starting restore | |
366 | backup: task ID of restore operation: 112 | |
367 | backup: Finished doing restore | |
368 | ||
369 | The following command restores all volumes that have entries in the file | |
370 | named F</tmp/restore>: | |
371 | ||
372 | % backup volsetrestore -file /tmp/restore | |
373 | Starting restore | |
374 | backup: task ID of restore operation: 113 | |
375 | backup: Finished doing restore | |
376 | ||
377 | The F</tmp/restore> file has the following contents: | |
378 | ||
379 | fs1.example.com b user.pat | |
380 | fs1.example.com b user.terry | |
381 | fs1.example.com b user.smith | |
382 | fs2.example.com c user.jones | |
383 | . . . | |
384 | . . . | |
385 | ||
386 | =head1 PRIVILEGE REQUIRED | |
387 | ||
388 | The issuer must be listed in the F</usr/afs/etc/UserList> file on every | |
389 | machine where the Backup Server or Volume Location (VL) Server is running, | |
390 | and on every file server machine that houses an affected volume. If the | |
391 | B<-localauth> flag is included, the issuer must instead be logged on to a | |
392 | server machine as the local superuser C<root>. | |
393 | ||
394 | =head1 SEE ALSO | |
395 | ||
396 | L<butc(5)>, | |
397 | L<backup(8)>, | |
398 | L<backup_addvolentry(8)>, | |
399 | L<backup_addvolset(8)>, | |
400 | L<backup_diskrestore(8)>, | |
401 | L<backup_dump(8)>, | |
402 | L<backup_volrestore(8)>, | |
403 | L<butc(8)> | |
404 | ||
405 | =head1 COPYRIGHT | |
406 | ||
407 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. | |
408 | ||
409 | This documentation is covered by the IBM Public License Version 1.0. It was | |
410 | converted from HTML to POD by software written by Chas Williams and Russ | |
411 | Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. |