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