Commit | Line | Data |
---|---|---|
e7a042ee KB |
1 | .\" Copyright (c) 1985, 1991, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
85d07773 | 3 | .\" |
ad787160 C |
4 | .\" Redistribution and use in source and binary forms, with or without |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
12 | .\" 3. All advertising materials mentioning features or use of this software | |
13 | .\" must display the following acknowledgement: | |
14 | .\" This product includes software developed by the University of | |
15 | .\" California, Berkeley and its contributors. | |
16 | .\" 4. Neither the name of the University nor the names of its contributors | |
17 | .\" may be used to endorse or promote products derived from this software | |
18 | .\" without specific prior written permission. | |
b42768a6 | 19 | .\" |
ad787160 C |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
30 | .\" SUCH DAMAGE. | |
85d07773 | 31 | .\" |
fd88f5c5 | 32 | .\" @(#)restore.8 8.4 (Berkeley) 5/1/95 |
ad787160 | 33 | .\" |
fd88f5c5 | 34 | .Dd May 1, 1995 |
70567b1c CL |
35 | .Dt RESTORE 8 |
36 | .Os BSD 4 | |
37 | .Sh NAME | |
38 | .Nm restore | |
39 | .Nd "restore files or file systems from backups made with dump" | |
40 | .Sh SYNOPSIS | |
41 | .Nm restore | |
079bb848 KM |
42 | .Fl i |
43 | .Op Fl chmvy | |
44 | .Op Fl b Ar blocksize | |
45 | .Op Fl f Ar file | |
46 | .Op Fl s Ar fileno | |
47 | .Nm restore | |
48 | .Fl R | |
49 | .Op Fl cvy | |
50 | .Op Fl b Ar blocksize | |
51 | .Op Fl f Ar file | |
52 | .Op Fl s Ar fileno | |
53 | .Nm restore | |
54 | .Fl r | |
55 | .Op Fl cvy | |
56 | .Op Fl b Ar blocksize | |
57 | .Op Fl f Ar file | |
58 | .Op Fl s Ar fileno | |
59 | .Nm restore | |
60 | .Fl t | |
61 | .Op Fl chvy | |
62 | .Op Fl b Ar blocksize | |
63 | .Op Fl f Ar file | |
64 | .Op Fl s Ar fileno | |
65 | .Op file ... | |
66 | .Nm restore | |
67 | .Fl x | |
68 | .Op Fl chmvy | |
69 | .Op Fl b Ar blocksize | |
70 | .Op Fl f Ar file | |
71 | .Op Fl s Ar fileno | |
72 | .Op file ... | |
73 | .Pp | |
74 | .in -\\n(iSu | |
75 | (The | |
76 | .Bx 4.3 | |
77 | option syntax is implemented for backward compatibility, but | |
78 | is not documented here.) | |
70567b1c | 79 | .Sh DESCRIPTION |
85d07773 | 80 | The |
70567b1c CL |
81 | .Nm restore |
82 | command performs the inverse function of | |
83 | .Xr dump 8 . | |
84 | A full backup of a file system may be restored and | |
85 | subsequent incremental backups layered on top of it. | |
86 | Single files and | |
87 | directory subtrees may be restored from full or partial | |
88 | backups. | |
89 | .Nm Restore | |
6fb9f654 KM |
90 | works across a network; |
91 | to do this see the | |
92 | .Fl f | |
93 | flag described below. | |
95c6920e KM |
94 | Other arguments to the command are file or directory |
95 | names specifying the files that are to be restored. | |
96 | Unless the | |
079bb848 KM |
97 | .Fl h |
98 | flag is specified (see below), | |
95c6920e KM |
99 | the appearance of a directory name refers to |
100 | the files and (recursively) subdirectories of that directory. | |
70567b1c | 101 | .Pp |
079bb848 | 102 | Exactly one of the following flags is required: |
70567b1c | 103 | .Bl -tag -width Ds |
079bb848 | 104 | .It Fl i |
70567b1c CL |
105 | This mode allows interactive restoration of files from a dump. |
106 | After reading in the directory information from the dump, | |
107 | .Nm restore | |
95c6920e KM |
108 | provides a shell like interface that allows the user to move |
109 | around the directory tree selecting files to be extracted. | |
110 | The available commands are given below; | |
111 | for those commands that require an argument, | |
112 | the default is the current directory. | |
70567b1c | 113 | .Bl -tag -width Fl |
70567b1c | 114 | .It Ic add Op Ar arg |
95c6920e KM |
115 | The current directory or specified argument is added to the list of |
116 | files to be extracted. | |
117 | If a directory is specified, then it and all its descendents are | |
118 | added to the extraction list | |
119 | (unless the | |
079bb848 KM |
120 | .Fl h |
121 | flag is specified on the command line). | |
95c6920e KM |
122 | Files that are on the extraction list are prepended with a ``*'' |
123 | when they are listed by | |
70567b1c | 124 | .Ic ls . |
6b46636d CL |
125 | .It Ic \&cd Ar arg |
126 | Change the current working directory to the specified argument. | |
70567b1c | 127 | .It Ic delete Op Ar arg |
95c6920e KM |
128 | The current directory or specified argument is deleted from the list of |
129 | files to be extracted. | |
130 | If a directory is specified, then it and all its descendents are | |
131 | deleted from the extraction list | |
132 | (unless the | |
079bb848 KM |
133 | .Fl h |
134 | flag is specified on the command line). | |
95c6920e KM |
135 | The most expedient way to extract most of the files from a directory |
136 | is to add the directory to the extraction list and then delete | |
137 | those files that are not needed. | |
70567b1c | 138 | .It Ic extract |
95c6920e | 139 | All the files that are on the extraction list are extracted |
70567b1c CL |
140 | from the dump. |
141 | .Nm Restore | |
95c6920e KM |
142 | will ask which volume the user wishes to mount. |
143 | The fastest way to extract a few files is to | |
144 | start with the last volume, and work towards the first volume. | |
6b46636d CL |
145 | .It Ic help |
146 | List a summary of the available commands. | |
147 | .It Ic \&ls Op Ar arg | |
148 | List the current or specified directory. | |
149 | Entries that are directories are appended with a ``/''. | |
150 | Entries that have been marked for extraction are prepended with a ``*''. | |
079bb848 KM |
151 | If the verbose |
152 | flag is set the inode number of each entry is also listed. | |
6b46636d CL |
153 | .It Ic pwd |
154 | Print the full pathname of the current working directory. | |
155 | .It Ic quit | |
156 | Restore immediately exits, | |
157 | even if the extraction list is not empty. | |
70567b1c | 158 | .It Ic setmodes |
78fda31e KM |
159 | All the directories that have been added to the extraction list |
160 | have their owner, modes, and times set; | |
70567b1c | 161 | nothing is extracted from the dump. |
78fda31e | 162 | This is useful for cleaning up after a restore has been prematurely aborted. |
70567b1c | 163 | .It Ic verbose |
95c6920e | 164 | The sense of the |
079bb848 KM |
165 | .Fl v |
166 | flag is toggled. | |
167 | When set, the verbose flag causes the | |
70567b1c | 168 | .Ic ls |
95c6920e KM |
169 | command to list the inode numbers of all entries. |
170 | It also causes | |
70567b1c | 171 | .Nm restore |
95c6920e | 172 | to print out information about each file as it is extracted. |
6b46636d | 173 | .El |
079bb848 KM |
174 | .It Fl R |
175 | .Nm Restore | |
176 | requests a particular tape of a multi volume set on which to restart | |
177 | a full restore | |
178 | (see the | |
179 | .Fl r | |
180 | flag below). | |
181 | This is useful if the restore has been interrupted. | |
182 | .It Fl r | |
183 | Restore (rebuild a file system). | |
184 | The target file system should be made pristine with | |
185 | .Xr newfs 8 , | |
186 | mounted and the user | |
187 | .Xr cd Ns 'd | |
188 | into the pristine file system | |
189 | before starting the restoration of the initial level 0 backup. If the | |
190 | level 0 restores successfully, the | |
191 | .Fl r | |
192 | flag may be used to restore | |
193 | any necessary incremental backups on top of the level 0. | |
194 | The | |
195 | .Fl r | |
196 | flag precludes an interactive file extraction and can be | |
197 | detrimental to one's health if not used carefully (not to mention | |
198 | the disk). An example: | |
199 | .Bd -literal -offset indent | |
200 | newfs /dev/rrp0g eagle | |
201 | mount /dev/rp0g /mnt | |
202 | cd /mnt | |
203 | ||
204 | restore rf /dev/rst8 | |
205 | .Ed | |
206 | .Pp | |
207 | Note that | |
208 | .Nm restore | |
209 | leaves a file | |
210 | .Pa restoresymtable | |
211 | in the root directory to pass information between incremental | |
212 | restore passes. | |
213 | This file should be removed when the last incremental has been | |
214 | restored. | |
215 | .Pp | |
216 | .Nm Restore , | |
217 | in conjunction with | |
218 | .Xr newfs 8 | |
219 | and | |
220 | .Xr dump 8 , | |
221 | may be used to modify file system parameters | |
222 | such as size or block size. | |
223 | .It Fl t | |
224 | The names of the specified files are listed if they occur | |
225 | on the backup. | |
226 | If no file argument is given, | |
227 | then the root directory is listed, | |
228 | which results in the entire content of the | |
229 | backup being listed, | |
230 | unless the | |
231 | .Fl h | |
232 | flag has been specified. | |
233 | Note that the | |
234 | .Fl t | |
235 | flag replaces the function of the old | |
236 | .Xr dumpdir 8 | |
237 | program. | |
238 | .ne 1i | |
239 | .It Fl x | |
240 | The named files are read from the given media. | |
241 | If a named file matches a directory whose contents | |
242 | are on the backup | |
243 | and the | |
244 | .Fl h | |
245 | flag is not specified, | |
246 | the directory is recursively extracted. | |
247 | The owner, modification time, | |
248 | and mode are restored (if possible). | |
249 | If no file argument is given, | |
250 | then the root directory is extracted, | |
251 | which results in the entire content of the | |
252 | backup being extracted, | |
253 | unless the | |
254 | .Fl h | |
255 | flag has been specified. | |
70567b1c CL |
256 | .El |
257 | .Pp | |
079bb848 | 258 | The following additional options may be specified: |
70567b1c | 259 | .Bl -tag -width Ds |
079bb848 KM |
260 | .It Fl b Ar blocksize |
261 | The number of kilobytes per dump record. | |
70567b1c CL |
262 | If the |
263 | .Fl b | |
264 | option is not specified, | |
265 | .Nm restore | |
079bb848 KM |
266 | tries to determine the block size dynamically. |
267 | .It Fl c | |
268 | Normally, | |
70567b1c | 269 | .Nm restore |
079bb848 KM |
270 | will try to determine dynamically whether the dump was made from an |
271 | old (pre-4.4) or new format file sytem. The | |
272 | .Fl c | |
273 | flag disables this check, and only allows reading a dump in the old | |
274 | format. | |
275 | .It Fl f Ar file | |
276 | Read the backup from | |
277 | .Ar file ; | |
278 | .Ar file | |
279 | may be a special device file | |
280 | like | |
281 | .Pa /dev/rmt12 | |
282 | (a tape drive), | |
283 | .Pa /dev/rsd1c | |
284 | (a disk drive), | |
285 | an ordinary file, | |
286 | or | |
287 | .Ql Fl | |
288 | (the standard input). | |
6fb9f654 KM |
289 | If the name of the file is of the form |
290 | .Dq host:file , | |
079bb848 KM |
291 | or |
292 | .Dq user@host:file , | |
6fb9f654 KM |
293 | .Nm restore |
294 | reads from the named file on the remote host using | |
295 | .Xr rmt 8 . | |
70567b1c | 296 | .Pp |
079bb848 KM |
297 | .It Fl h |
298 | Extract the actual directory, | |
6b46636d CL |
299 | rather than the files that it references. |
300 | This prevents hierarchical restoration of complete subtrees | |
301 | from the dump. | |
079bb848 KM |
302 | .It Fl m |
303 | Extract by inode numbers rather than by file name. | |
6b46636d CL |
304 | This is useful if only a few files are being extracted, |
305 | and one wants to avoid regenerating the complete pathname | |
306 | to the file. | |
079bb848 KM |
307 | .It Fl s Ar fileno |
308 | Read from the specified | |
309 | .Ar fileno | |
310 | on a multi-file tape. | |
311 | File numbering starts at 1. | |
312 | .It Fl v | |
0c7dc5b1 | 313 | Normally |
70567b1c | 314 | .Nm restore |
0c7dc5b1 KM |
315 | does its work silently. |
316 | The | |
079bb848 | 317 | .Fl v |
0c7dc5b1 | 318 | (verbose) |
079bb848 | 319 | flag causes it to type the name of each file it treats |
0c7dc5b1 | 320 | preceded by its file type. |
079bb848 KM |
321 | .It Fl y |
322 | Do not ask the user whether to abort the restore in the event of an error. | |
323 | Always try to skip over the bad block(s) and continue. | |
70567b1c CL |
324 | .El |
325 | .Sh DIAGNOSTICS | |
95c6920e KM |
326 | Complaints if it gets a read error. |
327 | If | |
079bb848 | 328 | .Fl y |
70567b1c CL |
329 | has been specified, or the user responds |
330 | .Ql y , | |
331 | .Nm restore | |
95c6920e | 332 | will attempt to continue the restore. |
70567b1c CL |
333 | .Pp |
334 | If a backup was made using more than one tape volume, | |
335 | .Nm restore | |
336 | will notify the user when it is time to mount the next volume. | |
95c6920e | 337 | If the |
079bb848 | 338 | .Fl x |
95c6920e | 339 | or |
079bb848 KM |
340 | .Fl i |
341 | flag has been specified, | |
70567b1c | 342 | .Nm restore |
95c6920e KM |
343 | will also ask which volume the user wishes to mount. |
344 | The fastest way to extract a few files is to | |
345 | start with the last volume, and work towards the first volume. | |
70567b1c | 346 | .Pp |
95c6920e | 347 | There are numerous consistency checks that can be listed by |
70567b1c | 348 | .Nm restore . |
95c6920e KM |
349 | Most checks are self-explanatory or can ``never happen''. |
350 | Common errors are given below. | |
70567b1c CL |
351 | .Pp |
352 | .Bl -tag -width Ds -compact | |
353 | .It Converting to new file system format. | |
95c6920e KM |
354 | A dump tape created from the old file system has been loaded. |
355 | It is automatically converted to the new file system format. | |
70567b1c CL |
356 | .Pp |
357 | .It <filename>: not found on tape | |
95c6920e KM |
358 | The specified file name was listed in the tape directory, |
359 | but was not found on the tape. | |
360 | This is caused by tape read errors while looking for the file, | |
361 | and from using a dump tape created on an active file system. | |
70567b1c CL |
362 | .Pp |
363 | .It expected next file <inumber>, got <inumber> | |
95c6920e | 364 | A file that was not listed in the directory showed up. |
70567b1c CL |
365 | This can occur when using a dump created on an active file system. |
366 | .Pp | |
367 | .It Incremental dump too low | |
95c6920e | 368 | When doing incremental restore, |
70567b1c | 369 | a dump that was written before the previous incremental dump, |
95c6920e | 370 | or that has too low an incremental level has been loaded. |
70567b1c CL |
371 | .Pp |
372 | .It Incremental dump too high | |
95c6920e | 373 | When doing incremental restore, |
70567b1c CL |
374 | a dump that does not begin its coverage where the previous incremental |
375 | dump left off, | |
95c6920e | 376 | or that has too high an incremental level has been loaded. |
70567b1c CL |
377 | .Pp |
378 | .It Tape read error while restoring <filename> | |
379 | .It Tape read error while skipping over inode <inumber> | |
380 | .It Tape read error while trying to resynchronize | |
381 | A tape (or other media) read error has occurred. | |
95c6920e KM |
382 | If a file name is specified, |
383 | then its contents are probably partially wrong. | |
384 | If an inode is being skipped or the tape is trying to resynchronize, | |
385 | then no extracted files have been corrupted, | |
386 | though files may not be found on the tape. | |
70567b1c CL |
387 | .Pp |
388 | .It resync restore, skipped <num> blocks | |
389 | After a dump read error, | |
390 | .Nm restore | |
95c6920e KM |
391 | may have to resynchronize itself. |
392 | This message lists the number of blocks that were skipped over. | |
70567b1c CL |
393 | .El |
394 | .Sh FILES | |
395 | .Bl -tag -width "./restoresymtable" -compact | |
396 | .It Pa /dev/rmt? | |
397 | the default tape drive | |
398 | .It Pa /tmp/rstdir* | |
399 | file containing directories on the tape. | |
400 | .It Pa /tmp/rstmode* | |
401 | owner, mode, and time stamps for directories. | |
402 | .It Pa \&./restoresymtable | |
403 | information passed between incremental restores. | |
404 | .El | |
405 | .Sh SEE ALSO | |
70567b1c CL |
406 | .Xr dump 8 , |
407 | .Xr newfs 8 , | |
408 | .Xr mount 8 , | |
6fb9f654 KM |
409 | .Xr mkfs 8 , |
410 | .Xr rmt 8 | |
70567b1c CL |
411 | .Sh BUGS |
412 | .Nm Restore | |
95c6920e | 413 | can get confused when doing incremental restores from |
079bb848 | 414 | dumps that were made on active file systems. |
70567b1c | 415 | .Pp |
95c6920e KM |
416 | A level zero dump must be done after a full restore. |
417 | Because restore runs in user code, | |
418 | it has no control over inode allocation; | |
079bb848 | 419 | thus a full dump must be done to get a new set of directories |
95c6920e KM |
420 | reflecting the new inode numbering, |
421 | even though the contents of the files is unchanged. | |
70567b1c CL |
422 | .Sh HISTORY |
423 | The | |
6b46636d | 424 | .Nm restore |
70567b1c CL |
425 | command appeared in |
426 | .Bx 4.2 . |