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