| 1 | =head1 NAME |
| 2 | |
| 3 | backup_diskrestore - Restores the entire contents of a partition |
| 4 | |
| 5 | =head1 SYNOPSIS |
| 6 | |
| 7 | =for html |
| 8 | <div class="synopsis"> |
| 9 | |
| 10 | B<backup diskrestore> S<<< B<-server> <I<machine to restore>> >>> |
| 11 | S<<< B<-partition> <I<partition to restore>> >>> |
| 12 | S<<< [B<-portoffset> <I<TC port offset>>+] >>> |
| 13 | S<<< [B<-newserver> <I<destination machine>>] >>> |
| 14 | S<<< [B<-newpartition> <I<destination partition>>] >>> |
| 15 | S<<< [B<-extension> <I<new volume name extension>>] >>> |
| 16 | [B<-dryrun> | B<-n>] [B<-localauth>] S<<< [B<-cell> <I<cell name>>] >>> [B<-help>] |
| 17 | |
| 18 | B<backup di> S<<< B<-s> <I<machine to restore>> >>> |
| 19 | S<<< B<-pa> <I<partition to restore>> >>> |
| 20 | S<<< [B<-po> <I<TC port offset>>+] >>> |
| 21 | S<<< [B<-news> <I<destination machine>>] >>> |
| 22 | S<<< [B<-newp> <I<destination partition>>] >>> |
| 23 | S<<< [B<-e> <I<new volume name extension>>] >>> [B<-dryrun> | B<-n>] [B<-l>] |
| 24 | S<<< [B<-c> <I<cell name>>] >>> [B<-h>] |
| 25 | |
| 26 | =for html |
| 27 | </div> |
| 28 | |
| 29 | =head1 DESCRIPTION |
| 30 | |
| 31 | The B<backup diskrestore> command restores all of the volumes for which |
| 32 | the Volume Location Database (VLDB) lists a read/write site on the |
| 33 | partition specified with the B<-server> and B<-partition> arguments. It is |
| 34 | useful if a disk or machine failure corrupts or destroys the data on an |
| 35 | entire partition. (To restore any read-only or backup volumes that resided |
| 36 | on the partition, use the B<vos release> and B<vos backup> commands, |
| 37 | respectively, after restoring the read/write version.) |
| 38 | |
| 39 | If restoring only selected volumes to a single site, it is usually more |
| 40 | efficient to use the B<backup volrestore> command. To restore multiple |
| 41 | volumes to many different sites, use the B<backup volsetrestore> command. |
| 42 | |
| 43 | (If the C<FILE YES> instruction appears in the |
| 44 | F</usr/afs/backup/CFG_I<device_name>> file on the Tape Coordinator machine |
| 45 | associated with the specified port offset, then the Backup System restores |
| 46 | data from the backup data file listed for that port offset in the Tape |
| 47 | Coordinator's F</usr/afs/backup/tapeconfig> file, instead of from |
| 48 | tape. For the sake of clarity, the following text refers to tapes only, |
| 49 | but the Backup System handles backup data files in much the same way.) |
| 50 | |
| 51 | The Backup System determines whether the read/write or backup version of |
| 52 | each volume was dumped more recently, and restores the dumps of that |
| 53 | version, starting with the most recent full dump. It resets the creation |
| 54 | timestamp of each restored volume to the date and time at which it begins |
| 55 | restoring the volume (the creation timestamp appears in the C<Creation> |
| 56 | field of the output from the B<vos examine> and B<vos listvol> commands). |
| 57 | |
| 58 | If all of the full and incremental dumps of all relevant volumes were not |
| 59 | written on compatible tape devices, use the B<-portoffset> argument to |
| 60 | list multiple port offset numbers in the order in which the tapes are |
| 61 | needed (first list the port offset for the full dump, second the port |
| 62 | offset for the level 1 incremental dump, and so on). This implies that the |
| 63 | full dumps of all relevant volumes must have been written to a type of |
| 64 | tape that the first Tape Coordinator can read, the level 1 incremental |
| 65 | dumps to a type of tape the second Tape Coordinator can read, and so |
| 66 | on. If dumps are on multiple incompatible tape types, use the B<backup |
| 67 | volrestore> command to restore individual volumes, or the B<backup |
| 68 | volsetrestore> command after defining groups of volumes that were dumped |
| 69 | to compatible tape types. For further discussion, see the I<OpenAFS |
| 70 | Administration Guide>. |
| 71 | |
| 72 | By default, the Backup System restores the contents of the specified |
| 73 | partition to that same partition. To restore the contents to an alternate |
| 74 | site, combine the following options as indicated. The Backup System |
| 75 | removes each volume from the original site, if it still exists, and |
| 76 | records the change of site in the VLDB. |
| 77 | |
| 78 | =over 4 |
| 79 | |
| 80 | =item * |
| 81 | |
| 82 | To restore to a different partition on the same file server machine, |
| 83 | provide the B<-newpartition> argument. |
| 84 | |
| 85 | =item * |
| 86 | |
| 87 | To restore to the partition with the same name on a different file server |
| 88 | machine, provide the B<-newserver> argument. |
| 89 | |
| 90 | =item * |
| 91 | |
| 92 | To restore to a completely different site, combine the B<-newserver> and |
| 93 | B<-newpartition> arguments. |
| 94 | |
| 95 | =back |
| 96 | |
| 97 | By default, the Backup System overwrites the contents of existing volumes |
| 98 | with the restored data. To create a new volume to house the restored data |
| 99 | instead, use the B<-extension> argument. The Backup System creates the new |
| 100 | volume at the site designated by the B<-newserver> and B<-newpartition> |
| 101 | arguments if they are used or the B<-server> and B<-partition> arguments |
| 102 | otherwise. It derives the volume name by adding the extension to the |
| 103 | read/write base name listed in the VLDB, and creates a new VLDB entry. The |
| 104 | command does not affect the existing volume in any way. However, if a |
| 105 | volume with the specified extension also already exists, the command |
| 106 | overwrites it. |
| 107 | |
| 108 | To print out a list of the tapes containing the needed dumps, without |
| 109 | actually performing the restore operation, include the B<-dryrun> flag |
| 110 | along with the other options to be used on the actual command. |
| 111 | |
| 112 | The Tape Coordinator's default response to this command is to access the |
| 113 | first tape it needs by invoking the C<MOUNT> instruction in the local |
| 114 | F<CFG_I<device_name>> file, or by prompting the backup operator to insert |
| 115 | the tape if there is no C<MOUNT> instruction. However, if the C<AUTOQUERY |
| 116 | NO> instruction appears in the F<CFG_I<device_name>> file, or if the |
| 117 | issuer of the B<butc> command included the B<-noautoquery> flag, the Tape |
| 118 | Coordinator instead expects the tape to be in the device already. If it |
| 119 | is not, or is the wrong tape, the Tape Coordinator invokes the C<MOUNT> |
| 120 | instruction or prompts the operator. It also invokes the C<MOUNT> |
| 121 | instruction or prompts for any additional tapes needed to complete the |
| 122 | restore operation; the backup operator must arrange to provide them. |
| 123 | |
| 124 | =head1 CAUTIONS |
| 125 | |
| 126 | If issuing this command to recover data after a disk crash or other |
| 127 | damage, be sure not to issue the B<vos syncserv> command first. Doing so |
| 128 | destroys the VLDB record of the volumes that resided on the partition. |
| 129 | |
| 130 | =head1 OPTIONS |
| 131 | |
| 132 | =over 4 |
| 133 | |
| 134 | =item B<-server> <I<machine to restore>> |
| 135 | |
| 136 | Names the file server machine that the VLDB lists as the site of the |
| 137 | volumes that need to be restored. |
| 138 | |
| 139 | =item B<-partition> <I<partition to restore>> |
| 140 | |
| 141 | Names the partition that the VLDB lists as the site of the volumes that |
| 142 | need to be restored. |
| 143 | |
| 144 | =item B<-portoffset> <I<TC port offset>>+ |
| 145 | |
| 146 | Specifies one or more port offset numbers (up to a maximum of 128), each |
| 147 | corresponding to a Tape Coordinator to use in the operation. If there is |
| 148 | more than one value, the Backup System uses the first one when restoring |
| 149 | the full dump of each volume, the second one when restoring the level 1 |
| 150 | incremental dump of each volume, and so on. It uses the final value in the |
| 151 | list when restoring dumps at the corresponding depth in the dump hierarchy |
| 152 | and at all lower levels. |
| 153 | |
| 154 | Provide this argument unless the default value of 0 (zero) is appropriate |
| 155 | for all dumps. If C<0> is just one of the values in the list, provide it |
| 156 | explicitly in the appropriate order. |
| 157 | |
| 158 | =item B<-newserver> <I<destination machine>> |
| 159 | |
| 160 | Names an alternate file server machine to which to restore the volumes. If |
| 161 | this argument is omitted, the volumes are restored to the file server |
| 162 | machine named by the B<-server> argument. |
| 163 | |
| 164 | =item B<-newpartition> <I<destination partition>> |
| 165 | |
| 166 | Names an alternate partition to which to restore the data. If this |
| 167 | argument is omitted, the volumes are restored to the partition named by |
| 168 | the B<-partition> argument. |
| 169 | |
| 170 | =item B<-extension> <I<new volume name extension>> |
| 171 | |
| 172 | Creates a new volume for each volume being restored, to house the restored |
| 173 | data. The Backup System derives the new volume's name by appending the |
| 174 | specified string to the read/write base name listed in the VLDB, and |
| 175 | creates a new VLDB volume entry. The Backup System preserves the contents |
| 176 | of the volumes on the partition, if any still exist. Any string other than |
| 177 | C<.readonly> or C<.backup> is acceptable, but the combination of the base |
| 178 | name and extension cannot exceed 22 characters in length. To use a period |
| 179 | to separate the extension from the name, specify it as the first character |
| 180 | of the string (as in C<.rst>, for example). |
| 181 | |
| 182 | =item B<-dryrun> | B<-n> |
| 183 | |
| 184 | Displays a list of the tapes necessary to perform the requested restore, |
| 185 | without actually performing the operation. |
| 186 | |
| 187 | =item B<-localauth> |
| 188 | |
| 189 | Constructs a server ticket using a key from the local |
| 190 | F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents |
| 191 | it to the Backup Server, Volume Server and VL Server during mutual |
| 192 | authentication. Do not combine this flag with the B<-cell> argument. For |
| 193 | more details, see L<backup(8)>. |
| 194 | |
| 195 | =item B<-cell> <I<cell name>> |
| 196 | |
| 197 | Names the cell in which to run the command. Do not combine this argument |
| 198 | with the B<-localauth> flag. For more details, see L<backup(8)>. |
| 199 | |
| 200 | =item B<-help> |
| 201 | |
| 202 | Prints the online help for this command. All other valid options are |
| 203 | ignored. |
| 204 | |
| 205 | =back |
| 206 | |
| 207 | =head1 OUTPUT |
| 208 | |
| 209 | If a tape error occurs during the restore operation, the Tape Coordinator |
| 210 | displays the following messages: |
| 211 | |
| 212 | Restore operation on volume I<name> failed due to tape error |
| 213 | Do you want to continue (y/n)? |
| 214 | |
| 215 | where I<name> is the name of the volume that was being restored when the |
| 216 | tape error occurred. Enter the value B<y> to continue the operation |
| 217 | without restoring the indicated volume or the value C<n> to terminate the |
| 218 | operation. In the latter case, the operator can then attempt to determine |
| 219 | the cause of the tape error. |
| 220 | |
| 221 | If the issuer includes the B<-dryrun> flag with the command, the following |
| 222 | string appears at the head of the list of the tapes necessary to perform |
| 223 | the restore operation: |
| 224 | |
| 225 | Tapes needed: |
| 226 | |
| 227 | =head1 EXAMPLES |
| 228 | |
| 229 | The following command restores the volumes for which the VLDB lists a |
| 230 | read/write site on the F</vicepd> partition of the machine |
| 231 | C<fs5.example.com>. The Tape Coordinator associated with port offset 3 |
| 232 | performs the operation. |
| 233 | |
| 234 | % backup diskrestore -server fs5.example.com \ |
| 235 | -partition /vicepd -portoffset 3 |
| 236 | |
| 237 | The following command restores the volumes for which the VLDB lists a |
| 238 | read/write site on the F</vicepb> partition of the machine C<fs1.example.com> |
| 239 | to a new site: the F</vicepa> partition on the machine C<fs3.example.com>. The |
| 240 | Tape Coordinator associated with port offset 0 performs the |
| 241 | operation. (The command appears here on two lines only for legibility.) |
| 242 | |
| 243 | % backup diskrestore -server fs1.example.com -partition /vicepb \ |
| 244 | -newserver fs3.example.com -newpartition /vicepa |
| 245 | |
| 246 | The following command lists the tapes required to restore the volumes for |
| 247 | which the VLDB lists a read/write site on the F</vicepm> partition of the |
| 248 | machine C<fs4.example.com>: |
| 249 | |
| 250 | % backup diskrestore -server fs4.example.com -partition /vicepm -dryrun |
| 251 | Tapes needed: |
| 252 | user.sunday1.1 |
| 253 | user.sunday1.2 |
| 254 | user.monday1.1 |
| 255 | user.tuesday1.1 |
| 256 | user.wednesday1.1 |
| 257 | |
| 258 | =head1 PRIVILEGE REQUIRED |
| 259 | |
| 260 | The issuer must be listed in the F</usr/afs/etc/UserList> file on every |
| 261 | machine where the Backup Server or Volume Location (VL) Server is running, |
| 262 | and on every file server machine that houses an affected volume. If the |
| 263 | B<-localauth> flag is included, the issuer must instead be logged on to a |
| 264 | server machine as the local superuser C<root>. |
| 265 | |
| 266 | =head1 SEE ALSO |
| 267 | |
| 268 | L<butc(5)>, |
| 269 | L<backup(8)>, |
| 270 | L<backup_dump(8)>, |
| 271 | L<backup_volrestore(8)>, |
| 272 | L<backup_volsetrestore(8)>, |
| 273 | L<butc(8)>, |
| 274 | L<vos_backup(1)>, |
| 275 | L<vos_examine(1)>, |
| 276 | L<vos_listvol(1)>, |
| 277 | L<vos_release(1)> |
| 278 | |
| 279 | =head1 COPYRIGHT |
| 280 | |
| 281 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. |
| 282 | |
| 283 | This documentation is covered by the IBM Public License Version 1.0. It was |
| 284 | converted from HTML to POD by software written by Chas Williams and Russ |
| 285 | Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. |