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