412 lines
12 KiB
Groff
412 lines
12 KiB
Groff
.\" Copyright (c) 1985, 1991, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the University of
|
|
.\" California, Berkeley and its contributors.
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)restore.8 8.2 (Berkeley) 12/11/93
|
|
.\" $FreeBSD$
|
|
.\" "
|
|
.Dd December 11, 1993
|
|
.Dt RESTORE 8
|
|
.Os BSD 4
|
|
.Sh NAME
|
|
.Nm restore
|
|
.Nd "restore files or file systems from backups made with dump"
|
|
.Sh SYNOPSIS
|
|
.Nm restore
|
|
.Ar key
|
|
.Op Ar name Ar ...
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm restore
|
|
command performs the inverse function of
|
|
.Xr dump 8 .
|
|
A full backup of a file system may be restored and
|
|
subsequent incremental backups layered on top of it.
|
|
Single files and
|
|
directory subtrees may be restored from full or partial
|
|
backups.
|
|
.Nm Restore
|
|
works across a network;
|
|
to do this see the
|
|
.Fl f
|
|
flag described below.
|
|
The actions
|
|
of
|
|
.Nm restore
|
|
are controlled by the given
|
|
.Cm key ,
|
|
which
|
|
is a string of characters containing
|
|
at most one function letter and possibly
|
|
one or more function modifiers.
|
|
Other arguments to the command are file or directory
|
|
names specifying the files that are to be restored.
|
|
Unless the
|
|
.Cm h
|
|
key is specified (see below),
|
|
the appearance of a directory name refers to
|
|
the files and (recursively) subdirectories of that directory.
|
|
.Pp
|
|
The function portion of
|
|
the key is specified by one of the following letters:
|
|
.Bl -tag -width Ds
|
|
.It Cm r
|
|
Restore (rebuild a file system).
|
|
The target file system should be made pristine with
|
|
.Xr newfs 8 ,
|
|
mounted and the
|
|
user
|
|
.Xr cd Ns 'd
|
|
into the pristine file system
|
|
before starting the restoration of the initial level 0 backup. If the
|
|
level 0 restores successfully, the
|
|
.Cm r
|
|
key may be used to restore
|
|
any necessary incremental backups on top of the level 0.
|
|
The
|
|
.Cm r
|
|
key precludes an interactive file extraction and can be
|
|
detrimental to one's health if not used carefully (not to mention
|
|
the disk). An example:
|
|
.Bd -literal -offset indent
|
|
newfs /dev/rrp0g eagle
|
|
mount /dev/rp0g /mnt
|
|
cd /mnt
|
|
|
|
restore rf /dev/rst8
|
|
.Ed
|
|
.Pp
|
|
Note that
|
|
.Nm restore
|
|
leaves a file
|
|
.Pa restoresymtable
|
|
in the root directory to pass information between incremental
|
|
restore passes.
|
|
This file should be removed when the last incremental has been
|
|
restored.
|
|
.Pp
|
|
.Nm Restore ,
|
|
in conjunction with
|
|
.Xr newfs 8
|
|
and
|
|
.Xr dump 8 ,
|
|
may be used to modify file system parameters
|
|
such as size or block size.
|
|
.It Cm R
|
|
.Nm Restore
|
|
requests a particular tape of a multi volume set on which to restart
|
|
a full restore
|
|
(see the
|
|
.Cm r
|
|
key above).
|
|
This is useful if the restore has been interrupted.
|
|
.It Cm x
|
|
The named files are read from the given media.
|
|
If a named file matches a directory whose contents
|
|
are on the backup
|
|
and the
|
|
.Cm h
|
|
key is not specified,
|
|
the directory is recursively extracted.
|
|
The owner, modification time,
|
|
and mode are restored (if possible).
|
|
If no file argument is given,
|
|
then the root directory is extracted,
|
|
which results in the entire content of the
|
|
backup being extracted,
|
|
unless the
|
|
.Cm h
|
|
key has been specified.
|
|
.It Cm t
|
|
The names of the specified files are listed if they occur
|
|
on the backup.
|
|
If no file argument is given,
|
|
then the root directory is listed,
|
|
which results in the entire content of the
|
|
backup being listed,
|
|
unless the
|
|
.Cm h
|
|
key has been specified.
|
|
Note that the
|
|
.Cm t
|
|
key replaces the function of the old
|
|
.Xr dumpdir 8
|
|
program.
|
|
.It Cm i
|
|
This mode allows interactive restoration of files from a dump.
|
|
After reading in the directory information from the dump,
|
|
.Nm restore
|
|
provides a shell like interface that allows the user to move
|
|
around the directory tree selecting files to be extracted.
|
|
The available commands are given below;
|
|
for those commands that require an argument,
|
|
the default is the current directory.
|
|
.Bl -tag -width Fl
|
|
.It Ic add Op Ar arg
|
|
The current directory or specified argument is added to the list of
|
|
files to be extracted.
|
|
If a directory is specified, then it and all its descendents are
|
|
added to the extraction list
|
|
(unless the
|
|
.Cm h
|
|
key is specified on the command line).
|
|
Files that are on the extraction list are prepended with a ``*''
|
|
when they are listed by
|
|
.Ic ls .
|
|
.It Ic \&cd Ar arg
|
|
Change the current working directory to the specified argument.
|
|
.It Ic delete Op Ar arg
|
|
The current directory or specified argument is deleted from the list of
|
|
files to be extracted.
|
|
If a directory is specified, then it and all its descendents are
|
|
deleted from the extraction list
|
|
(unless the
|
|
.Cm h
|
|
key is specified on the command line).
|
|
The most expedient way to extract most of the files from a directory
|
|
is to add the directory to the extraction list and then delete
|
|
those files that are not needed.
|
|
.It Ic extract
|
|
All the files that are on the extraction list are extracted
|
|
from the dump.
|
|
.Nm Restore
|
|
will ask which volume the user wishes to mount.
|
|
The fastest way to extract a few files is to
|
|
start with the last volume, and work towards the first volume.
|
|
.It Ic help
|
|
List a summary of the available commands.
|
|
.It Ic \&ls Op Ar arg
|
|
List the current or specified directory.
|
|
Entries that are directories are appended with a ``/''.
|
|
Entries that have been marked for extraction are prepended with a ``*''.
|
|
If the verbose key is set the inode number of each entry is also listed.
|
|
.It Ic pwd
|
|
Print the full pathname of the current working directory.
|
|
.It Ic quit
|
|
Restore immediately exits,
|
|
even if the extraction list is not empty.
|
|
.It Ic setmodes
|
|
All the directories that have been added to the extraction list
|
|
have their owner, modes, and times set;
|
|
nothing is extracted from the dump.
|
|
This is useful for cleaning up after a restore has been prematurely aborted.
|
|
.It Ic verbose
|
|
The sense of the
|
|
.Cm v
|
|
key is toggled.
|
|
When set, the verbose key causes the
|
|
.Ic ls
|
|
command to list the inode numbers of all entries.
|
|
It also causes
|
|
.Nm restore
|
|
to print out information about each file as it is extracted.
|
|
.El
|
|
.El
|
|
.Pp
|
|
The following characters may be used in addition to the letter
|
|
that selects the function desired.
|
|
.Bl -tag -width Ds
|
|
.It Cm b
|
|
The next argument to
|
|
.Nm restore
|
|
is used as the block size of the media (in kilobytes).
|
|
If the
|
|
.Fl b
|
|
option is not specified,
|
|
.Nm restore
|
|
tries to determine the media block size dynamically.
|
|
.It Cm f
|
|
The next argument to
|
|
.Nm restore
|
|
is used as the name of the archive instead
|
|
of
|
|
.Pa /dev/rst0 .
|
|
If the name of the file is of the form
|
|
.Dq host:file ,
|
|
.Nm restore
|
|
reads from the named file on the remote host using
|
|
.Xr rmt 8 .
|
|
If the name of the file is
|
|
.Ql Fl ,
|
|
.Nm restore
|
|
reads from standard input.
|
|
Thus,
|
|
.Xr dump 8
|
|
and
|
|
.Nm restore
|
|
can be used in a pipeline to dump and restore a file system
|
|
with the command
|
|
.Bd -literal -offset indent
|
|
dump 0f - /usr | (cd /mnt; restore xf -)
|
|
.Ed
|
|
.Pp
|
|
.It Cm h
|
|
.Nm Restore
|
|
extracts the actual directory,
|
|
rather than the files that it references.
|
|
This prevents hierarchical restoration of complete subtrees
|
|
from the dump.
|
|
.It Cm m
|
|
.Nm Restore
|
|
will extract by inode numbers rather than by file name.
|
|
This is useful if only a few files are being extracted,
|
|
and one wants to avoid regenerating the complete pathname
|
|
to the file.
|
|
.It Cm s
|
|
The next argument to
|
|
.Nm restore
|
|
is a number which
|
|
selects the file on a multi-file dump tape. File numbering
|
|
starts at 1.
|
|
.It Cm v
|
|
Normally
|
|
.Nm restore
|
|
does its work silently.
|
|
The
|
|
.Cm v
|
|
(verbose)
|
|
key causes it to type the name of each file it treats
|
|
preceded by its file type.
|
|
.It Cm y
|
|
.Nm Restore
|
|
will not ask whether it should abort the restore if it gets an error.
|
|
It will always try to skip over the bad block(s) and continue as
|
|
best it can.
|
|
.El
|
|
.Sh DIAGNOSTICS
|
|
Complaints about bad key characters.
|
|
.Pp
|
|
Complaints if it gets a read error.
|
|
If
|
|
.Cm y
|
|
has been specified, or the user responds
|
|
.Ql y ,
|
|
.Nm restore
|
|
will attempt to continue the restore.
|
|
.Pp
|
|
If a backup was made using more than one tape volume,
|
|
.Nm restore
|
|
will notify the user when it is time to mount the next volume.
|
|
If the
|
|
.Cm x
|
|
or
|
|
.Cm i
|
|
key has been specified,
|
|
.Nm restore
|
|
will also ask which volume the user wishes to mount.
|
|
The fastest way to extract a few files is to
|
|
start with the last volume, and work towards the first volume.
|
|
.Pp
|
|
There are numerous consistency checks that can be listed by
|
|
.Nm restore .
|
|
Most checks are self-explanatory or can ``never happen''.
|
|
Common errors are given below.
|
|
.Pp
|
|
.Bl -tag -width Ds -compact
|
|
.It Converting to new file system format.
|
|
A dump tape created from the old file system has been loaded.
|
|
It is automatically converted to the new file system format.
|
|
.Pp
|
|
.It <filename>: not found on tape
|
|
The specified file name was listed in the tape directory,
|
|
but was not found on the tape.
|
|
This is caused by tape read errors while looking for the file,
|
|
and from using a dump tape created on an active file system.
|
|
.Pp
|
|
.It expected next file <inumber>, got <inumber>
|
|
A file that was not listed in the directory showed up.
|
|
This can occur when using a dump created on an active file system.
|
|
.Pp
|
|
.It Incremental dump too low
|
|
When doing incremental restore,
|
|
a dump that was written before the previous incremental dump,
|
|
or that has too low an incremental level has been loaded.
|
|
.Pp
|
|
.It Incremental dump too high
|
|
When doing incremental restore,
|
|
a dump that does not begin its coverage where the previous incremental
|
|
dump left off,
|
|
or that has too high an incremental level has been loaded.
|
|
.Pp
|
|
.It Tape read error while restoring <filename>
|
|
.It Tape read error while skipping over inode <inumber>
|
|
.It Tape read error while trying to resynchronize
|
|
A tape (or other media) read error has occurred.
|
|
If a file name is specified,
|
|
then its contents are probably partially wrong.
|
|
If an inode is being skipped or the tape is trying to resynchronize,
|
|
then no extracted files have been corrupted,
|
|
though files may not be found on the tape.
|
|
.Pp
|
|
.It resync restore, skipped <num> blocks
|
|
After a dump read error,
|
|
.Nm restore
|
|
may have to resynchronize itself.
|
|
This message lists the number of blocks that were skipped over.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width "./restoresymtable" -compact
|
|
.It Pa /dev/rst0
|
|
the default tape drive
|
|
.It Pa /tmp/rstdir*
|
|
file containing directories on the tape.
|
|
.It Pa /tmp/rstmode*
|
|
owner, mode, and time stamps for directories.
|
|
.It Pa \&./restoresymtable
|
|
information passed between incremental restores.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr dump 8 ,
|
|
.Xr ft 8 ,
|
|
.Xr mount 8 ,
|
|
.Xr newfs 8 ,
|
|
.Xr rmt 8
|
|
.Sh BUGS
|
|
.Nm Restore
|
|
can get confused when doing incremental restores from
|
|
dump that were made on active file systems.
|
|
.Pp
|
|
A level zero dump must be done after a full restore.
|
|
Because restore runs in user code,
|
|
it has no control over inode allocation;
|
|
thus a full dump must be done to get a new set of directories
|
|
reflecting the new inode numbering,
|
|
even though the contents of the files is unchanged.
|
|
.Pp
|
|
To do a network restore, you have to run restore as root. This is due
|
|
to the previous security history of dump and restore. (restore is
|
|
written to be setuid root, but we are not certain all bugs are gone
|
|
from the restore code - run setuid at your own risk.)
|
|
.Sh HISTORY
|
|
The
|
|
.Nm restore
|
|
command appeared in
|
|
.Bx 4.2 .
|