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