doc/man-pages/pod8/backup_diskrestore.pod

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