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 | .\" |
ed554bc5 | 32 | .\" @(#)restore.8 8.2 (Berkeley) 12/11/93 |
ad787160 | 33 | .\" |
ed554bc5 | 34 | .Dd December 11, 1993 |
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 | |
42 | .Ar key | |
43 | .Op Ar name Ar ... | |
44 | .Sh DESCRIPTION | |
85d07773 | 45 | The |
70567b1c CL |
46 | .Nm restore |
47 | command performs the inverse function of | |
48 | .Xr dump 8 . | |
49 | A full backup of a file system may be restored and | |
50 | subsequent incremental backups layered on top of it. | |
51 | Single files and | |
52 | directory subtrees may be restored from full or partial | |
53 | backups. | |
54 | .Nm Restore | |
6fb9f654 KM |
55 | works across a network; |
56 | to do this see the | |
57 | .Fl f | |
58 | flag described below. | |
70567b1c CL |
59 | The actions |
60 | of | |
61 | .Nm restore | |
62 | are controlled by the given | |
63 | .Cm key , | |
64 | which | |
95c6920e KM |
65 | is a string of characters containing |
66 | at most one function letter and possibly | |
67 | one or more function modifiers. | |
68 | Other arguments to the command are file or directory | |
69 | names specifying the files that are to be restored. | |
70 | Unless the | |
70567b1c | 71 | .Cm h |
95c6920e KM |
72 | key is specified (see below), |
73 | the appearance of a directory name refers to | |
74 | the files and (recursively) subdirectories of that directory. | |
70567b1c | 75 | .Pp |
95c6920e KM |
76 | The function portion of |
77 | the key is specified by one of the following letters: | |
70567b1c CL |
78 | .Bl -tag -width Ds |
79 | .It Cm r | |
80 | Restore (rebuild a file system). | |
81 | The target file system should be made pristine with | |
82 | .Xr newfs 8 , | |
83 | mounted and the | |
84 | user | |
85 | .Xr cd Ns 'd | |
86 | into the pristine file system | |
87 | before starting the restoration of the initial level 0 backup. If the | |
88 | level 0 restores successfully, the | |
89 | .Cm r | |
90 | key may be used to restore | |
91 | any necessary incremental backups on top of the level 0. | |
92 | The | |
93 | .Cm r | |
94 | key precludes an interactive file extraction and can be | |
653ba8b6 | 95 | detrimental to one's health if not used carefully (not to mention |
70567b1c CL |
96 | the disk). An example: |
97 | .Bd -literal -offset indent | |
98 | newfs /dev/rrp0g eagle | |
99 | mount /dev/rp0g /mnt | |
100 | cd /mnt | |
101 | ||
102 | restore rf /dev/rst8 | |
103 | .Ed | |
104 | .Pp | |
95c6920e | 105 | Note that |
70567b1c | 106 | .Nm restore |
95c6920e | 107 | leaves a file |
70567b1c | 108 | .Pa restoresymtable |
95c6920e KM |
109 | in the root directory to pass information between incremental |
110 | restore passes. | |
70567b1c | 111 | This file should be removed when the last incremental has been |
95c6920e | 112 | restored. |
70567b1c CL |
113 | .Pp |
114 | .Nm Restore , | |
115 | in conjunction with | |
116 | .Xr newfs 8 | |
117 | and | |
118 | .Xr dump 8 , | |
119 | may be used to modify file system parameters | |
120 | such as size or block size. | |
121 | .It Cm R | |
122 | .Nm Restore | |
95c6920e KM |
123 | requests a particular tape of a multi volume set on which to restart |
124 | a full restore | |
125 | (see the | |
70567b1c | 126 | .Cm r |
95c6920e | 127 | key above). |
70567b1c CL |
128 | This is useful if the restore has been interrupted. |
129 | .It Cm x | |
130 | The named files are read from the given media. | |
131 | If a named file matches a directory whose contents | |
132 | are on the backup | |
95c6920e | 133 | and the |
70567b1c | 134 | .Cm h |
95c6920e KM |
135 | key is not specified, |
136 | the directory is recursively extracted. | |
137 | The owner, modification time, | |
138 | and mode are restored (if possible). | |
139 | If no file argument is given, | |
140 | then the root directory is extracted, | |
141 | which results in the entire content of the | |
70567b1c | 142 | backup being extracted, |
95c6920e | 143 | unless the |
70567b1c | 144 | .Cm h |
95c6920e | 145 | key has been specified. |
70567b1c | 146 | .It Cm t |
95c6920e | 147 | The names of the specified files are listed if they occur |
70567b1c | 148 | on the backup. |
95c6920e KM |
149 | If no file argument is given, |
150 | then the root directory is listed, | |
151 | which results in the entire content of the | |
70567b1c | 152 | backup being listed, |
95c6920e | 153 | unless the |
70567b1c | 154 | .Cm h |
95c6920e KM |
155 | key has been specified. |
156 | Note that the | |
70567b1c | 157 | .Cm t |
95c6920e | 158 | key replaces the function of the old |
70567b1c | 159 | .Xr dumpdir 8 |
95c6920e | 160 | program. |
70567b1c CL |
161 | .It Cm i |
162 | This mode allows interactive restoration of files from a dump. | |
163 | After reading in the directory information from the dump, | |
164 | .Nm restore | |
95c6920e KM |
165 | provides a shell like interface that allows the user to move |
166 | around the directory tree selecting files to be extracted. | |
167 | The available commands are given below; | |
168 | for those commands that require an argument, | |
169 | the default is the current directory. | |
70567b1c | 170 | .Bl -tag -width Fl |
70567b1c | 171 | .It Ic add Op Ar arg |
95c6920e KM |
172 | The current directory or specified argument is added to the list of |
173 | files to be extracted. | |
174 | If a directory is specified, then it and all its descendents are | |
175 | added to the extraction list | |
176 | (unless the | |
70567b1c | 177 | .Cm h |
95c6920e KM |
178 | key is specified on the command line). |
179 | Files that are on the extraction list are prepended with a ``*'' | |
180 | when they are listed by | |
70567b1c | 181 | .Ic ls . |
6b46636d CL |
182 | .It Ic \&cd Ar arg |
183 | Change the current working directory to the specified argument. | |
70567b1c | 184 | .It Ic delete Op Ar arg |
95c6920e KM |
185 | The current directory or specified argument is deleted from the list of |
186 | files to be extracted. | |
187 | If a directory is specified, then it and all its descendents are | |
188 | deleted from the extraction list | |
189 | (unless the | |
70567b1c | 190 | .Cm h |
95c6920e KM |
191 | key is specified on the command line). |
192 | The most expedient way to extract most of the files from a directory | |
193 | is to add the directory to the extraction list and then delete | |
194 | those files that are not needed. | |
70567b1c | 195 | .It Ic extract |
95c6920e | 196 | All the files that are on the extraction list are extracted |
70567b1c CL |
197 | from the dump. |
198 | .Nm Restore | |
95c6920e KM |
199 | will ask which volume the user wishes to mount. |
200 | The fastest way to extract a few files is to | |
201 | start with the last volume, and work towards the first volume. | |
6b46636d CL |
202 | .It Ic help |
203 | List a summary of the available commands. | |
204 | .It Ic \&ls Op Ar arg | |
205 | List the current or specified directory. | |
206 | Entries that are directories are appended with a ``/''. | |
207 | Entries that have been marked for extraction are prepended with a ``*''. | |
208 | If the verbose key is set the inode number of each entry is also listed. | |
209 | .It Ic pwd | |
210 | Print the full pathname of the current working directory. | |
211 | .It Ic quit | |
212 | Restore immediately exits, | |
213 | even if the extraction list is not empty. | |
70567b1c | 214 | .It Ic setmodes |
78fda31e KM |
215 | All the directories that have been added to the extraction list |
216 | have their owner, modes, and times set; | |
70567b1c | 217 | nothing is extracted from the dump. |
78fda31e | 218 | This is useful for cleaning up after a restore has been prematurely aborted. |
70567b1c | 219 | .It Ic verbose |
95c6920e | 220 | The sense of the |
70567b1c | 221 | .Cm v |
95c6920e KM |
222 | key is toggled. |
223 | When set, the verbose key causes the | |
70567b1c | 224 | .Ic ls |
95c6920e KM |
225 | command to list the inode numbers of all entries. |
226 | It also causes | |
70567b1c | 227 | .Nm restore |
95c6920e | 228 | to print out information about each file as it is extracted. |
6b46636d | 229 | .El |
70567b1c CL |
230 | .El |
231 | .Pp | |
95c6920e KM |
232 | The following characters may be used in addition to the letter |
233 | that selects the function desired. | |
70567b1c CL |
234 | .Bl -tag -width Ds |
235 | .It Cm b | |
0c7dc5b1 | 236 | The next argument to |
70567b1c CL |
237 | .Nm restore |
238 | is used as the block size of the media (in kilobytes). | |
239 | If the | |
240 | .Fl b | |
241 | option is not specified, | |
242 | .Nm restore | |
243 | tries to determine the media block size dynamically. | |
244 | .It Cm f | |
95c6920e | 245 | The next argument to |
70567b1c | 246 | .Nm restore |
95c6920e | 247 | is used as the name of the archive instead |
70567b1c CL |
248 | of |
249 | .Pa /dev/rmt? . | |
6fb9f654 KM |
250 | If the name of the file is of the form |
251 | .Dq host:file , | |
252 | .Nm restore | |
253 | reads from the named file on the remote host using | |
254 | .Xr rmt 8 . | |
70567b1c CL |
255 | If the name of the file is |
256 | .Ql Fl , | |
257 | .Nm restore | |
95c6920e KM |
258 | reads from standard input. |
259 | Thus, | |
70567b1c | 260 | .Xr dump 8 |
95c6920e | 261 | and |
70567b1c | 262 | .Nm restore |
95c6920e KM |
263 | can be used in a pipeline to dump and restore a file system |
264 | with the command | |
70567b1c CL |
265 | .Bd -literal -offset indent |
266 | dump 0f - /usr | (cd /mnt; restore xf -) | |
267 | .Ed | |
268 | .Pp | |
6b46636d CL |
269 | .It Cm h |
270 | .Nm Restore | |
271 | extracts the actual directory, | |
272 | rather than the files that it references. | |
273 | This prevents hierarchical restoration of complete subtrees | |
274 | from the dump. | |
275 | .It Cm m | |
276 | .Nm Restore | |
277 | will extract by inode numbers rather than by file name. | |
278 | This is useful if only a few files are being extracted, | |
279 | and one wants to avoid regenerating the complete pathname | |
280 | to the file. | |
281 | .It Cm s | |
282 | The next argument to | |
283 | .Nm restore | |
284 | is a number which | |
285 | selects the file on a multi-file dump tape. File numbering | |
286 | starts at 1. | |
70567b1c | 287 | .It Cm v |
0c7dc5b1 | 288 | Normally |
70567b1c | 289 | .Nm restore |
0c7dc5b1 KM |
290 | does its work silently. |
291 | The | |
70567b1c | 292 | .Cm v |
0c7dc5b1 KM |
293 | (verbose) |
294 | key causes it to type the name of each file it treats | |
295 | preceded by its file type. | |
70567b1c CL |
296 | .It Cm y |
297 | .Nm Restore | |
653ba8b6 | 298 | will not ask whether it should abort the restore if it gets an error. |
70567b1c | 299 | It will always try to skip over the bad block(s) and continue as |
95c6920e | 300 | best it can. |
70567b1c CL |
301 | .El |
302 | .Sh DIAGNOSTICS | |
95c6920e | 303 | Complaints about bad key characters. |
70567b1c | 304 | .Pp |
95c6920e KM |
305 | Complaints if it gets a read error. |
306 | If | |
70567b1c CL |
307 | .Cm y |
308 | has been specified, or the user responds | |
309 | .Ql y , | |
310 | .Nm restore | |
95c6920e | 311 | will attempt to continue the restore. |
70567b1c CL |
312 | .Pp |
313 | If a backup was made using more than one tape volume, | |
314 | .Nm restore | |
315 | will notify the user when it is time to mount the next volume. | |
95c6920e | 316 | If the |
70567b1c | 317 | .Cm x |
95c6920e | 318 | or |
70567b1c | 319 | .Cm i |
95c6920e | 320 | key has been specified, |
70567b1c | 321 | .Nm restore |
95c6920e KM |
322 | will also ask which volume the user wishes to mount. |
323 | The fastest way to extract a few files is to | |
324 | start with the last volume, and work towards the first volume. | |
70567b1c | 325 | .Pp |
95c6920e | 326 | There are numerous consistency checks that can be listed by |
70567b1c | 327 | .Nm restore . |
95c6920e KM |
328 | Most checks are self-explanatory or can ``never happen''. |
329 | Common errors are given below. | |
70567b1c CL |
330 | .Pp |
331 | .Bl -tag -width Ds -compact | |
332 | .It Converting to new file system format. | |
95c6920e KM |
333 | A dump tape created from the old file system has been loaded. |
334 | It is automatically converted to the new file system format. | |
70567b1c CL |
335 | .Pp |
336 | .It <filename>: not found on tape | |
95c6920e KM |
337 | The specified file name was listed in the tape directory, |
338 | but was not found on the tape. | |
339 | This is caused by tape read errors while looking for the file, | |
340 | and from using a dump tape created on an active file system. | |
70567b1c CL |
341 | .Pp |
342 | .It expected next file <inumber>, got <inumber> | |
95c6920e | 343 | A file that was not listed in the directory showed up. |
70567b1c CL |
344 | This can occur when using a dump created on an active file system. |
345 | .Pp | |
346 | .It Incremental dump too low | |
95c6920e | 347 | When doing incremental restore, |
70567b1c | 348 | a dump that was written before the previous incremental dump, |
95c6920e | 349 | or that has too low an incremental level has been loaded. |
70567b1c CL |
350 | .Pp |
351 | .It Incremental dump too high | |
95c6920e | 352 | When doing incremental restore, |
70567b1c CL |
353 | a dump that does not begin its coverage where the previous incremental |
354 | dump left off, | |
95c6920e | 355 | or that has too high an incremental level has been loaded. |
70567b1c CL |
356 | .Pp |
357 | .It Tape read error while restoring <filename> | |
358 | .It Tape read error while skipping over inode <inumber> | |
359 | .It Tape read error while trying to resynchronize | |
360 | A tape (or other media) read error has occurred. | |
95c6920e KM |
361 | If a file name is specified, |
362 | then its contents are probably partially wrong. | |
363 | If an inode is being skipped or the tape is trying to resynchronize, | |
364 | then no extracted files have been corrupted, | |
365 | though files may not be found on the tape. | |
70567b1c CL |
366 | .Pp |
367 | .It resync restore, skipped <num> blocks | |
368 | After a dump read error, | |
369 | .Nm restore | |
95c6920e KM |
370 | may have to resynchronize itself. |
371 | This message lists the number of blocks that were skipped over. | |
70567b1c CL |
372 | .El |
373 | .Sh FILES | |
374 | .Bl -tag -width "./restoresymtable" -compact | |
375 | .It Pa /dev/rmt? | |
376 | the default tape drive | |
377 | .It Pa /tmp/rstdir* | |
378 | file containing directories on the tape. | |
379 | .It Pa /tmp/rstmode* | |
380 | owner, mode, and time stamps for directories. | |
381 | .It Pa \&./restoresymtable | |
382 | information passed between incremental restores. | |
383 | .El | |
384 | .Sh SEE ALSO | |
70567b1c CL |
385 | .Xr dump 8 , |
386 | .Xr newfs 8 , | |
387 | .Xr mount 8 , | |
6fb9f654 KM |
388 | .Xr mkfs 8 , |
389 | .Xr rmt 8 | |
70567b1c CL |
390 | .Sh BUGS |
391 | .Nm Restore | |
95c6920e | 392 | can get confused when doing incremental restores from |
70567b1c CL |
393 | dump that were made on active file systems. |
394 | .Pp | |
95c6920e KM |
395 | A level zero dump must be done after a full restore. |
396 | Because restore runs in user code, | |
397 | it has no control over inode allocation; | |
398 | thus a full restore must be done to get a new set of directories | |
399 | reflecting the new inode numbering, | |
400 | even though the contents of the files is unchanged. | |
70567b1c CL |
401 | .Sh HISTORY |
402 | The | |
6b46636d | 403 | .Nm restore |
70567b1c CL |
404 | command appeared in |
405 | .Bx 4.2 . |