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