doc/man-pages/pod8/backup_volrestore.pod

   1 =head1 NAME
   2
   3 backup volrestore - Restores one or more volumes
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<backup volrestore> S<<< B<-server> <I<destination machine>> >>>
  11     S<<< B<-partition> <I<destination partition>> >>>
  12     S<<< B<-volume> <I<volume(s) to restore>>+ >>>
  13     S<<< [B<-extension> <I<new volume name extension>>] >>>
  14     S<<< [B<-date> <I<date from which to restore>>+] >>>
  15     S<<< [B<-portoffset> <I<TC port offsets>>+] >>> [B<-n>]
  16     [B<-localauth>] S<<< [B<-cell> <I<cell name>>] >>> [B<-help>]
  17
  18 B<backup volr> S<<< B<-s> <I<destination machine>> >>>
  19     S<<< B<-pa> <I<destination partition>> >>> S<<< B<-v> <I<volume(s) to restore>>+ >>>
  20     S<<< [B<-e> <I<new volume name extension>>] >>>
  21     S<<< [B<-d> <I<date from which to restore>>+] >>> S<<< [B<-po> <I<TC port offsets>>+] >>>
  22     [B<-n>] [B<-l>] S<<< [B<-c> <I<cell name>>] >>> [B<-h>]
  23
  24 =for html
  25 </div>
  26
  27 =head1 DESCRIPTION
  28
  29 The B<backup volrestore> command restores the contents of one or more
  30 volumes to the site indicated by the B<-server> and B<-partition>
  31 arguments. Use the command either to overwrite the contents of existing
  32 volumes with the restored data or to create new volumes while retaining
  33 the existing ones. The specified site does not have to be the current site
  34 for the volumes.
  35
  36 (If the C<FILE YES> instruction appears in the
  37 F</usr/afs/backup/CFG_I<device_name>> file associated with the specified
  38 port offset, then the B<backup volrestore> command restores data from the
  39 backup data file listed for that port offset in the Tape Coordinator's
  40 F</usr/afs/backup/tapeconfig> file, rather than from tape. For the sake of
  41 clarity, the following text refers to tapes only, but the Backup System
  42 handles backup data files in much the same way.)
  43
  44 The command's arguments can be combined as indicated:
  45
  46 =over 4
  47
  48 =item *
  49
  50 To preserve a volume's current contents and also create a new volume to
  51 house the restored version, use the B<-extension> argument.  The Backup
  52 System creates the new volume on the server and partition named by the
  53 B<-server> and B<-partition> arguments, assigns it the same name as the
  54 current volume with the addition of the specified extension, and creates a
  55 new Volume Location Database (VLDB) entry for it.  Creating a new volume
  56 enables the administrator to compare the two versions.
  57
  58 =item *
  59
  60 To overwrite a volume's existing contents with the restored version, omit
  61 the B<-extension> argument, and specify the site as indicated:
  62
  63 =over 4
  64
  65 =item *
  66
  67 To retain the current site, specify it with the B<-server> and
  68 B<-partition> arguments.
  69
  70 =item *
  71
  72 To move the volume to a different site while overwriting it, specify the
  73 new site with the B<-server> argument, B<-partition> argument, or
  74 both. The Backup System creates a new volume at that site, removes the
  75 existing volume, and updates the site information in the volume's VLDB
  76 entry. The backup version of the volume is not removed automatically from
  77 the original site, if it exists. Use the B<vos remove> command to remove
  78 it and the B<vos backup> command to create a backup version at the new
  79 site.
  80
  81 =back
  82
  83 =item *
  84
  85 To restore a volume that no longer exists in the file system, specify its
  86 name with the B<-volume> argument and use the B<-server> and B<-partition>
  87 arguments to place it at the desired site. The Backup System creates a new
  88 volume and new VLDB entry.
  89
  90 =back
  91
  92 In each case, the command sets each volume's creation date to the date and
  93 time at which it restores it. The creation date appears in the C<Creation>
  94 field in the output from the B<vos examine> and B<vos listvol> commands.
  95
  96 If restoring all of the volumes that resided on a single partition, it is
  97 usually more efficient to use the B<backup diskrestore> command. If
  98 restoring multiple volumes to many different sites, it can be more
  99 efficient to use the B<backup volsetrestore> command.
 100
 101 By default, the backup volrestore command restores the most recent full
 102 dump and all subsequent incremental dumps for each volume, bringing the
 103 restored volumes to the most current possible state. To restore the
 104 volumes to their state at some time in the past, use the B<-date>
 105 argument. The Backup System restores the most recent full dump and each
 106 subsequent incremental dump for which the I<clone date> of the volume
 107 included in the dump is before the indicated date and time (the clone date
 108 timestamp appears in the C<clone date> field of the output from the
 109 B<backup volinfo> command). For backup and read-only volumes, the clone
 110 date represents the time at which the volume was copied from its
 111 read/write source; for read/write volumes, it represents the time at which
 112 the volume was locked for inclusion in the dump. The resemblance of a
 113 restored volume to its actual state at the indicated time depends on the
 114 amount of time that elapsed between the volume's clone date in the last
 115 eligible dump and the specified time.
 116
 117 If the B<-volume> argument specifies the base (read/write) form of the
 118 volume name, the Backup System searches the Backup Database for the newest
 119 dump set that includes a dump of either the read/write or the backup
 120 version of the volume. It restores the dumps of that version of the
 121 volume, starting with the most recent full dump. If, in contrast, the
 122 volume name explicitly includes the C<.backup> or C<.readonly> extension,
 123 the Backup System restores dumps of the corresponding volume version only.
 124
 125 To generate a list of the tapes the Backup System needs to perform the
 126 restore operation, without actually performing it, combine the B<-n> flag
 127 with the options to be used on the actual command.
 128
 129 If all of the full and incremental dumps of all relevant volumes were not
 130 written to a type of tape that a single Tape Coordinator can read, use the
 131 B<-portoffset> argument to list multiple port offset numbers in the order
 132 in which the tapes are needed (first list the port offset for the full
 133 dump, second the port offset for the level 1 incremental dump, and so
 134 on). If restoring multiple volumes, the same ordered list of port offsets
 135 must apply to all of them. If not, either issue this command separately
 136 for each volume, or use the B<vos volsetrestore> command after defining
 137 groups of volumes that were dumped to compatible tape types. For further
 138 discussion, see the I<IBM AFS Administration Guide>.
 139
 140 The Tape Coordinator's default response to this command is to access the
 141 first tape it needs by invoking the B<MOUNT> instruction in the local
 142 F</usr/afs/backup/CFG_I<device_name>> file, or by prompting the backup
 143 operator to insert the tape if there is no C<MOUNT> instruction. However,
 144 if the C<AUTOQUERY NO> instruction appears in the F<CFG_I<device_name>>
 145 file, or if the issuer of the B<butc> command included the B<-noautoquery>
 146 flag, the Tape Coordinator instead expects the tape to be in the device
 147 already. If it is not, or is the wrong tape, the Tape Coordinator invokes
 148 the C<MOUNT> instruction or prompts the operator. It also invokes the
 149 C<MOUNT> instruction or prompts for any additional tapes needed to
 150 complete the restore operation; the backup operator must arrange to
 151 provide them.
 152
 153 =head1 OPTIONS
 154
 155 =over 4
 156
 157 =item B<-server> <I<destination machine>>
 158
 159 Names the file server machine on which to restore each volume. If this
 160 argument and the B<-partition> argument indicate a site other than the
 161 current site for each volume, and the B<-extension> argument is not also
 162 provided, the Backup System removes the existing volumes from their
 163 current sites, places the restored contents at the specified site, and
 164 changes the site information in the volume's VLDB entry.
 165
 166 =item B<-partition> <I<destination partition>>
 167
 168 Names the partition to which to restore each volume. If this argument and
 169 the B<-server> argument indicate a site other than the current site for
 170 each volume, and the B<-extension> argument is not also provided, the
 171 Backup System removes the existing volumes from their current sites,
 172 places the restored contents at the specified site, and changes the site
 173 information in the volume's VLDB entry.
 174
 175 =item B<-volume> <I<volume to restore>>+
 176
 177 Names one or more volumes to restore, using the volume name as listed in
 178 the Backup Database. Provide the base (read/write) name of each volume to
 179 have the Backup System search the Backup Database for the newest dump set
 180 that includes a dump of either the read/write or the backup version of the
 181 volume; it restores the dumps of that version of the volume, starting with
 182 the most recent full dump. If, in contrast, a volume name explicitly
 183 includes the C<.backup> or C<.readonly> extension, the Backup System
 184 restores dumps of the corresponding volume version only.
 185
 186 =item B<-extension> <I<new volume name extension>>
 187
 188 Creates a new volume to house the restored data, with a name derived by
 189 appending the specified string to each volume named by the B<-volume>
 190 argument. The Backup System creates a new VLDB entry for the volume. Any
 191 string other than C<.readonly> or C<.backup> is acceptable, but the
 192 combination of the existing volume name and extension cannot exceed 22
 193 characters in length. To use a period to separate the extension from the
 194 name, specify it as the first character of the string (as in C<.rst>, for
 195 example).
 196
 197 =item B<-date> <I<date from which to restore>>+
 198
 199 Specifies a date and optionally time; the restored volume includes data
 200 from dumps performed before the date only. Provide a value in the format
 201 I<mm/dd/yyyy> [I<hh>:I<MM>], where the required I<mm/dd/yyyy> portion
 202 indicates the month (I<mm>), day (I<dd>), and year (I<yyyy>), and the
 203 optional I<hh:MM> portion indicates the hour and minutes in 24-hour format
 204 (for example, the value C<14:36> represents 2:36 p.m.). If omitted, the
 205 time defaults to 59 seconds after midnight (00:00:59 hours).
 206
 207 Valid values for the year range from C<1970> to C<2037>; higher values are
 208 not valid because the latest possible date in the standard UNIX
 209 representation is in February 2038. The command interpreter automatically
 210 reduces any later date to the maximum value.
 211
 212 If this argument is omitted, the Backup System restores all possible dumps
 213 including the most recently created.
 214
 215 =item B<-portoffset> <I<TC port offest>>+
 216
 217 Specifies one or more port offset numbers (up to a maximum of 128), each
 218 corresponding to a Tape Coordinator to use in the operation. If there is
 219 more than one value, the Backup System uses the first one when restoring
 220 the full dump of each volume, the second one when restoring the level 1
 221 incremental dump of each volume, and so on. It uses the final value in the
 222 list when restoring dumps at the corresponding depth in the dump hierarchy
 223 and all dumps at lower levels.
 224
 225 Provide this argument unless the default value of 0 (zero) is appropriate
 226 for all dumps. If C<0> is just one of the values in the list, provide it
 227 explicitly in the appropriate order.
 228
 229 =item B<-n>
 230
 231 Displays the list of tapes that contain the dumps required by the restore
 232 operation, without actually performing the operation.
 233
 234 =item B<-localauth>
 235
 236 Constructs a server ticket using a key from the local
 237 F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
 238 it to the Backup Server, Volume Server and VL Server during mutual
 239 authentication. Do not combine this flag with the B<-cell> argument. For
 240 more details, see L<backup(8)>.
 241
 242 =item B<-cell> <I<cell name>>
 243
 244 Names the cell in which to run the command. Do not combine this argument
 245 with the B<-localauth> flag. For more details, see L<backup(8)>.
 246
 247 =item B<-help>
 248
 249 Prints the online help for this command. All other valid options are
 250 ignored.
 251
 252 =back
 253
 254 =head1 OUTPUT
 255
 256 If the issuer includes the B<-n> flag with the command, the following
 257 string appears at the head of the list of the tapes necessary to complete
 258 the restore operation.
 259
 260    Tapes needed:
 261
 262 =head1 EXAMPLES
 263
 264 The following command restores the volume user.pat to partition F</vicepa>
 265 on machine C<fs5.abc.com>:
 266
 267    % backup volrestore -server fs5.abc.com -partition a -volume user.pat
 268
 269 The following command restores the volumes C<user.smith> and C<user.terry>
 270 to partition F</vicepb> on machine C<fs4.abc.com>, adding a C<.rst>
 271 extension to each volume name and preserving the existing C<user.smith>
 272 and C<user.terry> volumes.  Only dumps created before 5:00 p.m. on 31
 273 January 1998 are restored. (The command is shown here on multiple lines
 274 only for legibility reasons.)
 275
 276    % backup volrestore -server fs4.abc.com -partition b  \
 277                        -volume user.smith user.terry  \
 278                        -extension .rst -date 1/31/1998 17:00
 279
 280 The following command restores the volume user.pat to partition F</vicepb>
 281 on machine C<fs4.abc.com>. The Tape Coordinator with port offset 1 handles
 282 the tape containing the full dump; the Tape Coordinator with port offset 0
 283 handles all tapes containing incremental dumps. (The command is shown here
 284 on two lines only for legibility reasons.)
 285
 286    % backup volrestore -server fs5.abc.com -partition a  \
 287                        -volume user.pat -portoffset 1 0
 288
 289 =head1 PRIVILEGE REQUIRED
 290
 291 The issuer must be listed in the F</usr/afs/etc/UserList> file on every
 292 machine where the Backup Server or Volume Location (VL) Server is running,
 293 and on every file server machine that houses an affected volume. If the
 294 B<-localauth> flag is included, the issuer must instead be logged on to a
 295 server machine as the local superuser C<root>.
 296
 297 =head1 SEE ALSO
 298
 299 L<butc(5)>,
 300 L<backup(8)>,
 301 L<backup_dump(8)>,
 302 L<backup_diskrestore(8)>,
 303 L<backup_volsetrestore(8)>,
 304 L<butc(8)>,
 305 L<vos_backup(1)>,
 306 L<vos_remove(1)>
 307
 308 =head1 COPYRIGHT
 309
 310 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 311
 312 This documentation is covered by the IBM Public License Version 1.0.  It was
 313 converted from HTML to POD by software written by Chas Williams and Russ
 314 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.