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