Change -n to -dryrun for backup subcommands
[openafs.git] / 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<-dryrun>]
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<-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<-portoffset> <I<TC port offest>>+
220
221 Specifies one or more port offset numbers (up to a maximum of 128), each
222 corresponding to a Tape Coordinator to use in the operation. If there is
223 more than one value, the Backup System uses the first one when restoring
224 the full dump of each volume, the second one when restoring the level 1
225 incremental dump of each volume, and so on. It uses the final value in the
226 list when restoring dumps at the corresponding depth in the dump hierarchy
227 and all dumps at lower levels.
228
229 Provide this argument unless the default value of 0 (zero) is appropriate
230 for all dumps. If C<0> is just one of the values in the list, provide it
231 explicitly in the appropriate order.
232
233 =item B<-dryrun>
234
235 Displays the list of tapes that contain the dumps required by the restore
236 operation, without actually performing the operation.
237
238 =item B<-localauth>
239
240 Constructs a server ticket using a key from the local
241 F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
242 it to the Backup Server, Volume Server and VL Server during mutual
243 authentication. Do not combine this flag with the B<-cell> argument. For
244 more details, see L<backup(8)>.
245
246 =item B<-cell> <I<cell name>>
247
248 Names the cell in which to run the command. Do not combine this argument
249 with the B<-localauth> flag. For more details, see L<backup(8)>.
250
251 =item B<-help>
252
253 Prints the online help for this command. All other valid options are
254 ignored.
255
256 =back
257
258 =head1 OUTPUT
259
260 If the issuer includes the B<-dryrun> flag with the command, the following
261 string appears at the head of the list of the tapes necessary to complete
262 the restore operation.
263
264    Tapes needed:
265
266 =head1 EXAMPLES
267
268 The following command restores the volume user.pat to partition F</vicepa>
269 on machine C<fs5.abc.com>:
270
271    % backup volrestore -server fs5.abc.com -partition a -volume user.pat
272
273 The following command restores the volumes C<user.smith> and C<user.terry>
274 to partition F</vicepb> on machine C<fs4.abc.com>, adding a C<.rst>
275 extension to each volume name and preserving the existing C<user.smith>
276 and C<user.terry> volumes.  Only dumps created before 5:00 p.m. on 31
277 January 1998 are restored. (The command is shown here on multiple lines
278 only for legibility reasons.)
279
280    % backup volrestore -server fs4.abc.com -partition b  \
281                        -volume user.smith user.terry  \
282                        -extension .rst -date 1/31/1998 17:00
283
284 The following command restores the volume user.pat to partition F</vicepb>
285 on machine C<fs4.abc.com>. The Tape Coordinator with port offset 1 handles
286 the tape containing the full dump; the Tape Coordinator with port offset 0
287 handles all tapes containing incremental dumps. (The command is shown here
288 on two lines only for legibility reasons.)
289
290    % backup volrestore -server fs5.abc.com -partition a  \
291                        -volume user.pat -portoffset 1 0
292
293 =head1 PRIVILEGE REQUIRED
294
295 The issuer must be listed in the F</usr/afs/etc/UserList> file on every
296 machine where the Backup Server or Volume Location (VL) Server is running,
297 and on every file server machine that houses an affected volume. If the
298 B<-localauth> flag is included, the issuer must instead be logged on to a
299 server machine as the local superuser C<root>.
300
301 =head1 SEE ALSO
302
303 L<butc(5)>,
304 L<backup(8)>,
305 L<backup_dump(8)>,
306 L<backup_diskrestore(8)>,
307 L<backup_volsetrestore(8)>,
308 L<butc(8)>,
309 L<vos_backup(1)>,
310 L<vos_remove(1)>
311
312 =head1 COPYRIGHT
313
314 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
315
316 This documentation is covered by the IBM Public License Version 1.0.  It was
317 converted from HTML to POD by software written by Chas Williams and Russ
318 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.