1 .\" Copyright (c) 1985, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
32 .\" $Id: restore.8.in,v 1.8 2000/03/08 11:25:58 stelian Exp $
36 .Os "restore __VERSION__"
39 .Nd "restore files or file systems from backups made with dump"
45 .Op Fl D Ar filesystem
100 .Op Fl T Ar directory
106 option syntax is implemented for backward compatibility but
107 is not documented here.)
111 command performs the inverse function of
113 A full backup of a file system may be restored and
114 subsequent incremental backups layered on top of it.
116 directory subtrees may be restored from full or partial
119 works across a network;
122 flag described below.
123 Other arguments to the command are file or directory
124 names specifying the files that are to be restored.
127 flag is specified (see below),
128 the appearance of a directory name refers to
129 the files and (recursively) subdirectories of that directory.
131 Exactly one of the following flags is required:
134 This mode allows comparison of files from a dump.
136 reads the backup and compares its contents with files present on the
138 It first changes its working directory to the root of the filesystem
139 that was dumped and compares the tape with the files in its new
142 This mode allows interactive restoration of files from a dump.
143 After reading in the directory information from the dump,
145 provides a shell like interface that allows the user to move
146 around the directory tree selecting files to be extracted.
147 The available commands are given below;
148 for those commands that require an argument,
149 the default is the current directory.
152 The current directory or specified argument is added to the list of
153 files to be extracted.
154 If a directory is specified, then it and all its descendents are
155 added to the extraction list
158 flag is specified on the command line).
159 Files that are on the extraction list are prepended with a
161 when they are listed by
164 Change the current working directory to the specified argument.
165 .It Ic delete Op Ar arg
166 The current directory or specified argument is deleted from the list of
167 files to be extracted.
168 If a directory is specified, then it and all its descendents are
169 deleted from the extraction list
172 flag is specified on the command line).
173 The most expedient way to extract most of the files from a directory
174 is to add the directory to the extraction list and then delete
175 those files that are not needed.
177 All files on the extraction list are extracted
180 will ask which volume the user wishes to mount.
181 The fastest way to extract a few files is to
182 start with the last volume and work towards the first volume.
184 List a summary of the available commands.
185 .It Ic \&ls Op Ar arg
186 List the current or specified directory.
187 Entries that are directories are appended with a
189 Entries that have been marked for extraction are prepended with a ``*''.
191 flag is set, the inode number of each entry is also listed.
193 Print the full pathname of the current working directory.
195 Restore immediately exits,
196 even if the extraction list is not empty.
198 All directories that have been added to the extraction list
199 have their owner, modes, and times set;
200 nothing is extracted from the dump.
201 This is useful for cleaning up after a restore has been prematurely aborted.
206 When set, the verbose flag causes the
208 command to list the inode numbers of all entries.
211 to print out information about each file as it is extracted.
215 requests a particular tape of a multi-volume set on which to restart
220 This is useful if the restore has been interrupted.
222 Restore (rebuild) a file system.
223 The target file system should be made pristine with
225 mounted, and the user
227 into the pristine file system
228 before starting the restoration of the initial level 0 backup. If the
229 level 0 restores successfully, the
231 flag may be used to restore
232 any necessary incremental backups on top of the level 0.
235 flag precludes an interactive file extraction and can be
236 detrimental to one's health (not to mention the disk) if not used carefully.
238 .Bd -literal -offset indent
250 in the root directory to pass information between incremental
252 This file should be removed when the last incremental has been
260 may be used to modify file system parameters
261 such as size or block size.
263 The names of the specified files are listed if they occur
265 If no file argument is given,
266 the root directory is listed,
267 which results in the entire content of the
271 flag has been specified.
274 flag replaces the function of the old
282 The named files are read from the given media.
283 If a named file matches a directory whose contents
287 flag is not specified,
288 the directory is recursively extracted.
289 The owner, modification time,
290 and mode are restored (if possible).
291 If no file argument is given,
292 the root directory is extracted,
293 which results in the entire content of the
294 backup being extracted,
297 flag has been specified.
303 The following additional options may be specified:
305 .It Fl b Ar blocksize
306 The number of kilobytes per dump record.
309 option is not specified,
311 tries to determine the media block size dynamically.
315 will try to determine dynamically whether the dump was made from an
316 old (pre-4.4) or new format file system. The
318 flag disables this check, and only allows reading a dump in the old
320 .It Fl D Ar filesystem
323 flag allows the user to specify the filesystem name when using
327 option to check the backup.
332 may be a special device file
341 (the standard input).
342 If the name of the file is of the form
347 reads from the named file on the remote host using
351 Use Kerberos authentication when contacting the remote tape server.
352 (Only available if this options was enabled when
357 Extract the actual directory,
358 rather than the files that it references.
359 This prevents hierarchical restoration of complete subtrees
362 Extract by inode numbers rather than by file name.
363 This is useful if only a few files are being extracted,
364 and one wants to avoid regenerating the complete pathname
367 Enables the multi-volume feature (for reading dumps made using
370 option of dump). The name specified with
372 is treated as a prefix and
374 tries to read in sequence from <prefix>001, <prefix>002 etc.
380 to only print file names. Files are not extracted.
382 Read from the specified
384 on a multi-file tape.
385 File numbering starts at 1.
386 .It Fl T Ar directory
389 flag allows the user to specify a directory to use for the storage of
390 temporary files. The default value is /tmp. This flag is most useful
391 when restoring files after having booted from a floppy. There might be little
392 or no space on the floppy filesystem, but another source of space might exist.
394 When creating certain types of files, restore may generate a warning
395 diagnostic if they already exist in the target directory.
398 (unlink) flag causes restore to remove old entries before attempting
403 does its work silently.
407 flag causes it to type the name of each file it treats
408 preceded by its file type.
410 Get the list of the files to be listed or extracted from the text file
412 instead of reading them on the command line. This can be used in
419 should contain file names separated by newlines.
421 Do not ask the user whether to abort the restore in the event of an error.
422 Always try to skip over the bad block(s) and continue.
425 Complains if it gets a read error.
428 has been specified, or the user responds
431 will attempt to continue the restore.
433 If a backup was made using more than one tape volume,
435 will notify the user when it is time to mount the next volume.
440 flag has been specified,
442 will also ask which volume the user wishes to mount.
443 The fastest way to extract a few files is to
444 start with the last volume, and work towards the first volume.
446 There are numerous consistency checks that can be listed by
448 Most checks are self-explanatory or can
450 Common errors are given below.
452 .Bl -tag -width Ds -compact
453 .It Converting to new file system format
454 A dump tape created from the old file system has been loaded.
455 It is automatically converted to the new file system format.
457 .It <filename>: not found on tape
458 The specified file name was listed in the tape directory,
459 but was not found on the tape.
460 This is caused by tape read errors while looking for the file,
461 and from using a dump tape created on an active file system.
463 .It expected next file <inumber>, got <inumber>
464 A file that was not listed in the directory showed up.
465 This can occur when using a dump created on an active file system.
467 .It Incremental dump too low
468 When doing an incremental restore,
469 a dump that was written before the previous incremental dump,
470 or that has too low an incremental level has been loaded.
472 .It Incremental dump too high
473 When doing an incremental restore,
474 a dump that does not begin its coverage where the previous incremental
476 or that has too high an incremental level has been loaded.
478 .It Tape read error while restoring <filename>
479 .It Tape read error while skipping over inode <inumber>
480 .It Tape read error while trying to resynchronize
481 A tape (or other media) read error has occurred.
482 If a file name is specified,
483 its contents are probably partially wrong.
484 If an inode is being skipped or the tape is trying to resynchronize,
485 no extracted files have been corrupted,
486 though files may not be found on the tape.
488 .It resync restore, skipped <num> blocks
489 After a dump read error,
491 may have to resynchronize itself.
492 This message lists the number of blocks that were skipped over.
495 If the following environment variable exists it will be utilized by
498 .Bl -tag -width "TMPDIR" -compact
500 If no -f option was specified,
502 will use the device specified via
510 .Qq user@host:tapename .
512 The directory given in
517 to store temporary files.
519 The environment variable
521 will be used to determine the pathname of the remote
526 uses the contents of this variable to determine the name of the
527 remote shell command to use when doing a network restore (rsh, ssh etc.).
528 If this variable is not set,
530 will be used, but only root will be able to do a network restore.
532 .Bl -tag -width "./restoresymtable" -compact
534 the default tape drive
536 file containing directories on the tape
538 owner, mode, and time stamps for directories
539 .It Pa \&./restoresymtable
540 information passed between incremental restores
549 can get confused when doing incremental restores from
550 dumps that were made on active file systems.
552 A level 0 dump must be done after a full restore.
556 it has no control over inode allocation;
557 thus a full dump must be done to get a new set of directories
558 reflecting the new inode numbering,
559 even though the content of the files is unchanged.
565 are generated with a unique name based on the date of the dump
566 and the process ID (see
575 allows you to restart a
577 operation that may have been interrupted, the temporary files should
578 be the same across different processes.
579 In all other cases, the files are unique because it is possible to
580 have two different dumps started at the same time, and separate
581 operations shouldn't conflict with each other.
583 To do a network restore, you have to run restore as root or use
584 a remote shell replacement (see RSH variable). This is due
585 to the previous security history of dump and restore. (restore is
586 written to be setuid root, but we are not certain all bugs are gone
587 from the restore code - run setuid at your own risk.)
591 backup suit was ported to Linux's Second Extended File System
592 by Remy Card <card@Linux.EU.Org>. He maintained the initial versions
593 of dump (up and including 0.4b4, released in january 1997).
595 Starting with 0.4b5, the new maintainer is Stelian Pop
601 backup suit is available from
603 http://dump.sourceforge.net