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