| blob | c4a94f813b53a3b442bf21239fa56b04adac7dba |
1 .\" $NetBSD: restore.8,v 1.51 2007/04/30 12:33:13 tron Exp $
2 .\"
3 .\" Copyright (c) 1985, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)restore.8 8.4 (Berkeley) 5/1/95
31 .\"
32 .Dd April 30, 2007
33 .Dt RESTORE 8
34 .Os
35 .Sh NAME
36 .Nm restore ,
37 .Nm rrestore
38 .Nd "restore files or file systems from backups made with dump"
39 .Sh SYNOPSIS
40 .Nm
41 .Fl i
42 .Op Fl cdhmuvyN
43 .Op Fl b Ar bsize
44 .Op Fl D Ar algorithm
45 .Op Fl f Ar file
46 .Op Fl M Ar mfile
47 .Op Fl s Ar fileno
48 .Nm
49 .Fl R
50 .Op Fl cduvyN
51 .Op Fl b Ar bsize
52 .Op Fl D Ar algorithm
53 .Op Fl f Ar file
54 .Op Fl M Ar mfile
55 .Op Fl s Ar fileno
56 .Nm
57 .Fl r
58 .Op Fl cduvyN
59 .Op Fl b Ar bsize
60 .Op Fl D Ar algorithm
61 .Op Fl f Ar file
62 .Op Fl M Ar mfile
63 .Op Fl s Ar fileno
64 .Nm
65 .Fl t
66 .Op Fl cdhuvy
67 .Op Fl b Ar bsize
68 .Op Fl f Ar file
69 .Op Fl s Ar fileno
70 .Op Ar
71 .Nm
72 .Fl x
73 .Op Fl cdhmuvyN
74 .Op Fl b Ar bsize
75 .Op Fl D Ar algorithm
76 .Op Fl f Ar file
77 .Op Fl M Ar mfile
78 .Op Fl s Ar fileno
79 .Op Ar
80 .Pp
81 .in -\n[indent-synopsis]u
82 (The
83 .Bx 4.3
84 option syntax is implemented for backward compatibility, but
85 is not documented here.)
86 .Sh DESCRIPTION
87 The
88 .Nm
89 command performs the inverse function of
90 .Xr dump 8 .
91 A full backup of a file system may be restored and
92 subsequent incremental backups layered on top of it.
93 Single files and
94 directory subtrees may be restored from full or partial
95 backups.
96 .Nm
97 works across a network;
98 to do this see the
99 .Fl f
100 flag described below.
101 Other arguments to the command are file or directory
102 names specifying the files that are to be restored.
103 Unless the
104 .Fl h
105 flag is specified (see below),
106 the appearance of a directory name refers to
107 the files and (recursively) subdirectories of that directory.
108 .Pp
109 If any file arguments are given with the
110 .Fl x
111 flag,
112 or specified in the command shell with the
113 .Fl i
114 flag,
115 the permissions of the root directory
116 .Em will not
117 be applied to the current directory,
118 unless one of those file arguments explicitly represents the root inode
119 .Po e.g.:
120 a literal
121 .Sq \&.
122 .Pc .
123 This is a change from the traditional behaviour,
124 which used to be to always prompt the user.
125 .Pp
126 Exactly one of the following flags is required:
127 .Bl -tag -width Ds
128 .It Fl i
129 This mode allows interactive restoration of files from a dump.
130 After reading in the directory information from the dump,
131 .Nm
132 provides a shell like interface that allows the user to move
133 around the directory tree selecting files to be extracted.
134 The available commands are given below;
135 for those commands that require an argument,
136 the default is the current directory.
137 .Bl -tag -width Fl
138 .It Ic add Op Ar arg
139 The current directory or specified argument is added to the list of
140 files to be extracted.
141 If a directory is specified, then it and all its descendants are
142 added to the extraction list
143 (unless the
144 .Fl h
145 flag is specified on the command line).
146 Files that are on the extraction list are prepended with a
147 .Dq *
148 when they are listed by
149 .Ic ls .
150 .It Ic \&cd Ar arg
151 Change the current working directory to the specified argument.
152 .It Ic delete Op Ar arg
153 The current directory or specified argument is deleted from the list of
154 files to be extracted.
155 If a directory is specified, then it and all its descendants are
156 deleted from the extraction list
157 (unless the
158 .Fl h
159 flag is specified on the command line).
160 The most expedient way to extract most of the files from a directory
161 is to add the directory to the extraction list and then delete
162 those files that are not needed.
163 .It Ic extract
164 All the files that are on the extraction list are extracted
165 from the dump.
166 .Nm
167 will ask which volume the user wishes to mount.
168 The fastest way to extract a few files is to
169 start with the last volume, and work towards the first volume.
170 .It Ic help , \&?
171 List a summary of the available commands.
172 .It Ic \&ls Op Ar arg
173 List the current or specified directory.
174 Entries that are directories are appended with a
175 .Dq / .
176 Entries that have been marked for extraction are prepended with a
177 .Dq * .
178 If the verbose
179 flag is set the inode number of each entry is also listed.
180 .It Ic pwd
181 Print the full pathname of the current working directory.
182 .It Ic quit , Ic xit
183 Restore immediately exits,
184 even if the extraction list is not empty.
185 .It Ic setmodes
186 All the directories that have been added to the extraction list
187 have their owner, modes, and times set;
188 nothing is extracted from the dump.
189 This is useful for cleaning up after a restore has been prematurely aborted.
190 .It Ic verbose
191 The sense of the
192 .Fl v
193 flag is toggled.
194 When set, the verbose flag causes the
195 .Ic ls
196 command to list the inode numbers of all entries.
197 It also causes
198 .Nm
199 to print out information about each file as it is extracted.
200 .It Ic what
201 List dump header information.
202 .It Ic Debug
203 Enable debugging.
204 .El
205 .It Fl R
206 .Nm
207 requests a particular tape of a multi volume set on which to restart
208 a full restore
209 (see the
210 .Fl r
211 flag below).
212 This is useful if the restore has been interrupted.
213 .It Fl r
214 Restore (rebuild a file system).
215 The target file system should be made pristine with
216 .Xr newfs 8 ,
217 mounted and the user
218 .Xr cd 1 Ns 'd
219 into the pristine file system
220 before starting the restoration of the initial level 0 backup.
221 If the level 0 restores successfully, the
222 .Fl r
223 flag may be used to restore
224 any necessary incremental backups on top of the level 0.
225 The
226 .Fl r
227 flag precludes an interactive file extraction and can be
228 detrimental to one's health if not used carefully (not to mention
229 the disk).
230 An example:
231 .Bd -literal -offset indent
232 newfs /dev/rsd0g
233 mount /dev/sd0g /mnt
234 cd /mnt
236 restore rf /dev/rst0
237 .Ed
238 .Pp
239 Note that
240 .Nm
241 leaves a file
242 .Pa restoresymtable
243 in the root directory to pass information between incremental
244 restore passes.
245 This file should be removed when the last incremental has been
246 restored.
247 .Pp
248 .Nm ,
249 in conjunction with
250 .Xr newfs 8
251 and
252 .Xr dump 8 ,
253 may be used to modify file system parameters
254 such as size or block size.
255 .It Fl t
256 The names of the specified files are listed if they occur
257 on the backup.
258 If no file argument is given,
259 then the root directory is listed,
260 which results in the entire content of the
261 backup being listed,
262 unless the
263 .Fl h
264 flag has been specified.
265 Note that the
266 .Fl t
267 flag replaces the function of the old
268 .Ic dumpdir
269 program.
270 .ne 1i
271 .It Fl x
272 The named files are read from the given media.
273 If a named file matches a directory whose contents
274 are on the backup
275 and the
276 .Fl h
277 flag is not specified,
278 the directory is recursively extracted.
279 The owner, modification time,
280 and mode are restored (if possible).
281 If no file argument is given,
282 then the root directory is extracted,
283 which results in the entire content of the
284 backup being extracted,
285 unless the
286 .Fl h
287 flag has been specified.
288 .El
289 .Pp
290 The following additional options may be specified:
291 .Bl -tag -width Ds
292 .It Fl b Ar bsize
293 The number of kilobytes per dump record.
294 If the
295 .Fl b
296 option is not specified,
297 .Nm
298 tries to determine the block size dynamically.
299 .It Fl c
300 Normally,
301 .Nm
302 will try to determine dynamically whether the dump was made from an
303 old (pre-4.4) or new format file system.
304 The
305 .Fl c
306 flag disables this check, and only allows reading a dump in the old
307 format.
308 .It Fl D Ar algorithm
309 Computes the digest of each regular files using the
310 .Ar algorithm
311 and output to standard output.
312 The
313 .Ar algorithm
314 is one of
315 .Ar md5 ,
316 .Ar rmd160 ,
317 or
318 .Ar sha1 .
319 This option doesn't imply
320 .Fl N .
321 .It Fl d
322 Enable debugging.
323 .It Fl f Ar file
324 Read the backup from
325 .Ar file ;
326 .Ar file
327 may be a special device file
328 like
329 .Pa /dev/rst0
330 (a tape drive),
331 .Pa /dev/rsd1c
332 (a disk drive),
333 an ordinary file,
334 or
335 .Ql Fl
336 (the standard input).
337 If the name of the file is of the form
338 .Dq host:file ,
339 or
340 .Dq user@host:file ,
341 .Nm
342 reads from the named file on the remote host using
343 .Xr rmt 8 .
344 If the name of the file is
345 .Ql Fl ,
346 .Nm
347 reads from standard input.
348 Thus,
349 .Xr dump 8
350 and
351 .Nm
352 can be used in a pipeline to dump and restore a file system
353 with the command
354 .Bd -literal -offset indent
355 dump 0f - /usr | (cd /mnt; restore xf -)
356 .Ed
357 .Pp
358 .It Fl h
359 Extract the actual directory,
360 rather than the files that it references.
361 This prevents hierarchical restoration of complete subtrees
362 from the dump.
363 .It Fl M Ar mfile
364 Do not set the file flags on restore.
365 Instead, append an
366 .Xr mtree 8
367 specification to
368 .Ar mfile ,
369 which can be used to restore file flags with a command such as
370 .Bd -literal -offset indent
371 sort mfile | mtree -e -i -u
372 .Ed
373 .It Fl m
374 Extract by inode numbers rather than by file name.
375 This is useful if only a few files are being extracted,
376 and one wants to avoid regenerating the complete pathname
377 to the file.
378 .It Fl N
379 Do not perform actual writing to disk.
380 .It Fl s Ar fileno
381 Read from the specified
382 .Ar fileno
383 on a multi-file tape.
384 File numbering starts at 1.
385 .It Fl u
386 The
387 .Fl u
388 (unlink)
389 flag removes files before extracting them.
390 This is useful when an executable file is in use.
391 Ignored if
392 .Fl t
393 or
394 .Fl N
395 flag is given.
396 .It Fl v
397 Normally
398 .Nm
399 does its work silently.
400 The
401 .Fl v
402 (verbose)
403 flag causes it to type the name of each file it treats
404 preceded by its file type.
405 .It Fl y
406 Do not ask the user whether to abort the restore in the event of an error.
407 Always try to skip over the bad block(s) and continue.
408 .El
409 .Sh ENVIRONMENT
410 If the following environment variable exists it will be used by
411 .Nm :
412 .Bl -tag -width "TMPDIR" -compact
413 .It TMPDIR
414 The directory given in TMPDIR will be used
415 instead of
416 .Pa /tmp
417 to store temporary files.
418 Refer to
419 .Xr environ 7
420 for more information.
421 .El
422 .Sh FILES
423 .Bl -tag -width "./restoresymtable" -compact
424 .It Pa /dev/nrst0
425 default tape unit to use.
426 Taken from
427 .Dv _PATH_DEFTAPE
428 in
429 .Pa /usr/include/paths.h .
430 .It Pa /dev/rst*
431 raw SCSI tape interface
432 .It Pa /tmp/rstdir*
433 file containing directories on the tape.
434 .It Pa /tmp/rstmode*
435 owner, mode, and time stamps for directories.
436 .It Pa \&./restoresymtable
437 information passed between incremental restores.
438 .El
439 .Sh DIAGNOSTICS
440 Complains if it gets a read error.
441 If
442 .Fl y
443 has been specified, or the user responds
444 .Ql y ,
445 .Nm
446 will attempt to continue the restore.
447 .Pp
448 If a backup was made using more than one tape volume,
449 .Nm
450 will notify the user when it is time to mount the next volume.
451 If the
452 .Fl x
453 or
454 .Fl i
455 flag has been specified,
456 .Nm
457 will also ask which volume the user wishes to mount.
458 The fastest way to extract a few files is to
459 start with the last volume, and work towards the first volume.
460 .Pp
461 There are numerous consistency checks that can be listed by
462 .Nm .
463 Most checks are self-explanatory or can
464 .Dq never happen .
465 Common errors are given below.
466 .Pp
467 .Bl -tag -width Ds -compact
468 .It Converting to new file system format.
469 A dump tape created from the old file system has been loaded.
470 It is automatically converted to the new file system format.
471 .Pp
472 .It \*[Lt]filename\*[Gt]: not found on tape
473 The specified file name was listed in the tape directory,
474 but was not found on the tape.
475 This is caused by tape read errors while looking for the file,
476 and from using a dump tape created on an active file system.
477 .Pp
478 .It expected next file \*[Lt]inumber\*[Gt], got \*[Lt]inumber\*[Gt]
479 A file that was not listed in the directory showed up.
480 This can occur when using a dump created on an active file system.
481 .Pp
482 .It Incremental dump too low
483 When doing incremental restore,
484 a dump that was written before the previous incremental dump,
485 or that has too low an incremental level has been loaded.
486 .Pp
487 .It Incremental dump too high
488 When doing incremental restore,
489 a dump that does not begin its coverage where the previous incremental
490 dump left off,
491 or that has too high an incremental level has been loaded.
492 .Pp
493 .It Tape read error while restoring \*[Lt]filename\*[Gt]
494 .It Tape read error while skipping over inode \*[Lt]inumber\*[Gt]
495 .It Tape read error while trying to resynchronize
496 A tape (or other media) read error has occurred.
497 If a file name is specified,
498 then its contents are probably partially wrong.
499 If an inode is being skipped or the tape is trying to resynchronize,
500 then no extracted files have been corrupted,
501 though files may not be found on the tape.
502 .Pp
503 .It resync restore, skipped \*[Lt]num\*[Gt] blocks
504 After a dump read error,
505 .Nm
506 may have to resynchronize itself.
507 This message lists the number of blocks that were skipped over.
508 .El
509 .Sh SEE ALSO
510 .Xr rcmd 1 ,
511 .Xr rcmd 3 ,
512 .Xr environ 7 ,
513 .Xr dump 8 ,
514 .Xr mount 8 ,
515 .Xr newfs 8 ,
516 .Xr rmt 8
517 .Sh HISTORY
518 The
519 .Nm
520 command appeared in
521 .Bx 4.2 .
522 .Sh BUGS
523 .Nm
524 can get confused when doing incremental restores from
525 dumps that were made on active file systems.
526 .Pp
527 A level zero dump must be done after a full restore.
528 Because
529 .Nm
530 runs in user code,
531 it has no control over inode allocation;
532 thus a full dump must be done to get a new set of directories
533 reflecting the new inode numbering,
534 even though the content of the files is unchanged.
535 .Pp
536 The temporary files
537 .Pa /tmp/rstdir*
538 and
539 .Pa /tmp/rstmode*
540 are generated with a unique name based on the date of the dump
541 and the process ID (see
542 .Xr mktemp 3 ) ,
543 except for when
544 .Fl r
545 or
546 .Fl R
547 is used.
548 Because
549 .Fl R
550 allows you to restart a
551 .Fl r
552 operation that may have been interrupted, the temporary files should
553 be the same across different processes.
554 In all other cases, the files are unique because it is possible to
555 have two different dumps started at the same time, and separate
556 operations shouldn't conflict with each other.