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<-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.