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>>] >>> 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>]
  14
  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>]
  18
  19 =for html
  20 </div>
  21
  22 =head1 DESCRIPTION
  23
  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.
  29
  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.)
  37
  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.
  42
  43 Indicate the volumes to restore by providing either the B<-name> argument
  44 or the B<-file> argument:
  45
  46 =over 4
  47
  48 =item *
  49
  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.
  56
  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.
  67
  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
  76 volume version only.
  77
  78 =item *
  79
  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.
  87
  88 =back
  89
  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>.
 103
 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.
 111
 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.
 116
 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.
 127
 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
 139 provide them.
 140
 141 =head1 OPTIONS
 142
 143 =over 4
 144
 145 =item B<-name> <I<volume set name>>
 146
 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.
 150
 151 =item B<-file> <I<file name>>
 152
 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.
 156
 157 Each volume's entry must appear on its own (unbroken) line in the file,
 158 and have the following format:
 159
 160     <machine> <partition> <volume> [<comments> ...]
 161
 162 where
 163
 164 =over 4
 165
 166 =item <machine>
 167
 168 Names the file server machine to which to restore the volume.
 169
 170 =item <partition>
 171
 172 Names the partition to which to restore the volume.
 173
 174 =item <volume>
 175
 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
 183 version only.
 184
 185 =item <comments> ...
 186
 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.
 190
 191 =back
 192
 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
 196 them.
 197
 198 =item B<-extension> <I<new volume name extension>>
 199
 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).
 209
 210 =item B<-portoffset> <I<TC port offset>>+
 211
 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.
 219
 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.
 223
 224 =item B<-n>
 225
 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.
 231
 232 =item B<-localauth>
 233
 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)>.
 239
 240 =item B<-cell> <I<cell name>>
 241
 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)>.
 244
 245 =item B<-help>
 246
 247 Prints the online help for this command. All other valid options are
 248 ignored.
 249
 250 =back
 251
 252 =head1 OUTPUT
 253
 254 If the B<-n> flag is not provided, the command displays a unique task ID
 255 number for the operation, in two places:
 256
 257 =over 4
 258
 259 =item *
 260
 261 In the shell window, directly following the command line.
 262
 263 =item *
 264
 265 In the Tape Coordinator window, if the butc process was started at debug
 266 level 1.
 267
 268 =back
 269
 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.
 274
 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.
 282
 283 The format of each line is as follows (the output is shown here on two
 284 lines only for legibility reasons):
 285
 286    <machine> <partition> <volume_dumped> # as <volume_restored>; \
 287        <tape_name> (<tape_ID>); pos <position_number>; <date>
 288
 289 where
 290
 291 =over 4
 292
 293 =item <machine>
 294
 295 Names the file server machine that currently houses the volume, as listed
 296 in the VLDB.
 297
 298 =item <partition>
 299
 300 Names the partition that currently houses the volume, as listed in the
 301 VLDB.
 302
 303 =item <volume_dumped>
 304
 305 Specifies the version (read/write or backup) of the volume that was
 306 dumped, as listed in the Backup Database.
 307
 308 =item <volume_restored>
 309
 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>).
 314
 315 =item <tape_name>
 316
 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.
 320
 321 =item <tape_ID>
 322
 323 The tape ID of the tape containing the dump of the volume, from the Backup
 324 Database.
 325
 326 =item <position_number>
 327
 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.
 332
 333 =item <date>
 334
 335 The date and time when the volume was dumped.
 336
 337 =back
 338
 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.
 344
 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.
 351
 352 =head1 EXAMPLES
 353
 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.
 359
 360    % backup volsetrestore -name data.restore
 361    Starting restore
 362    backup: task ID of restore operation: 112
 363    backup: Finished doing restore
 364
 365 The following command restores all volumes that have entries in the file
 366 named F</tmp/restore>:
 367
 368    % backup volsetrestore -file /tmp/restore
 369    Starting restore
 370    backup: task ID of restore operation: 113
 371    backup: Finished doing restore
 372
 373 The F</tmp/restore> file has the following contents:
 374
 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
 379           .         .     .
 380           .         .     .
 381
 382 =head1 PRIVILEGE REQUIRED
 383
 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>.
 389
 390 =head1 SEE ALSO
 391
 392 L<butc(5)>,
 393 L<backup(8)>,
 394 L<backup_addvolentry(8)>,
 395 L<backup_addvolset(8)>,
 396 L<backup_diskrestore(8)>,
 397 L<backup_dump(8)>,
 398 L<backup_volrestore(8)>,
 399 L<butc(8)>
 400
 401 =head1 COPYRIGHT
 402
 403 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 404
 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.