restore(8)restore(8)NAME
restore, rrestore - Restores files from tapes written with the dump or
rdump command, respectively
SYNOPSIS
/usr/sbin/restore -[function_option] [modifier_flag...] [argument...]
/usr/sbin/rrestore -f dump_file -[function_option] [modifier_flag...]
[argument...]
The restore and rrestore commands are used to read files and any asso‐
ciated extended attributes from a local or remote tape, respectively,
to local file systems.
OPTIONS
Function Options
This option permits interactive restoration of files read from the
tape. After reading directory information from the tape device, the
restore or rrestore commands provide a shell-like interface that allows
you to select the files you want to read. Some of the interactive com‐
mands require as an arg parameter a subdirectory or filename. When the
arg parameter is unspecified, the default directory is the current one.
The interactive commands are explained in the following list: Lists
files in the current directory or the directory specified with the arg
parameter. Directory entries are appended with a / (slash) character.
Entries that have been marked for reading are prepended with a *
(asterisk) character. When the -v modifier flag is used, the inode
number of each entry is also listed. Changes the current directory to
the directory specified with the arg parameter. Prints the pathname of
the current directory to the standard output device. Adds the files in
the current directory or the files specified by arg to the list of
files to be read from the tape (except when the -h option is used).
Files on the list of files to be read are prepended with the * (aster‐
isk) character when they are listed with the ls interactive command.
Deletes all the files in the current directory or the files specified
by the arg parameter from the list of files to be read from the tape.
Except when the -h option is specified, all files and all files in sub‐
directories of a directory specified with the arg parameter are
deleted.
An expedient way to select wanted files from any directory whose
files are stored on the tape is to add the directory to the list
of files to be read and then delete the ones that are not
wanted. Reads all files on the list of files to be read from
the tape. The restore or rrestore command asks which volume you
want to mount and whether the access modes of (dot) are
affected.
A fast way to read a few files from the tape device is to start
with the last volume and work toward the first volume. Sets
owner, access modes, and file creation times for all directories
that have been added to the files-to-read list; nothing is read
from the tape. This interactive command is useful for cleaning
up files after a restore or rrestore command has been prema‐
turely aborted. Toggles the -v modifier (see the -v flag
below). When set, the verbose option causes the ls command to
list the inode numbers of all files in the list of files to
read. This interactive command also causes the restore or
rrestore command to output information about each file to the
output device when the file is read. Lists a summary of the
available interactive commands. Outputs the tape header infor‐
mation to the standard output device. Exits immediately, even
when the all the files on list of files to read have not been
read. Toggles the debugging mode. Same as quit command. The
tape is read and all files are loaded into the current working
directory. The -r function option should only be used to
restore a complete dump into an empty file system, or to restore
a previous incremental dump or rdump to the file system after a
full level 0 (zero) restoration of files. For example:
/sbin/newfs /dev/rdisk/dsk0g eagle /sbin/mount
/dev/disk/dsk0g /mnt cd mnt restore -r
These four line entries are a typical sequence of commands to
restore a complete set of files from tape to the raw disk whose
device name is /dev/rdisk/dsk0g and whose parameters are
described in the /etc/disktab file under the name eagle. The
file system name is /dev/disk/dsk0g and the directory where the
file system is mounted and to which the files are written from
the default tape device is called /mnt.
Other restore or rrestore operations may be called to restore
additional files from a previous incremental dump or rdump to
the tape device. Note that the restore or rrestore process
writes a file named restoresymtab to the current directory. The
restoresymtab file is used by these processes to provide infor‐
mation for incremental file restorations only; this scratch file
has no other use and so should be removed when files from the
last incremental storage medium has been restored. The
restoresymtab filename is appended with the node identifier of
the cluster member (member id), which is always zero (0) for
standalone systems. The restore or rrestore command requests a
particular tape of a multivolume set on which to restart a full
restore (see the -r option). This allows restore or rrestore to
be interrupted and then restarted. The files specified by the
name parameter are listed when they are stored on the tape.
When a name parameter is not specified, all files in the root
directory stored on the tape are listed, except when the -h
option is specified. The files specified by the name parameter
are read from the tape device. When the name parameter matches
a directory whose contents are stored on the tape, and the -h
option is not specified, the directory is recursively searched
until all files have been read. The file owner, time of modifi‐
cation, and access mode are restored when possible. When no
file is specified with the name parameter, the root directory is
read from the tape device. Reading of the root directory
results in storage of the entire file content from the tape,
except when the -h option has been specified.
Modifier Flags
The argument that follows this modifier option is used as the block
size of the tape (in kilobytes). When this modifier flag is not speci‐
fied, restore or rrestore determines tape block size dynamically as
long as the maximum number of tape blocks to be read (blocking factor)
is less than 128k. Otherwise, include this option with the appropriate
blocking factor. Reads an old style dump tape (pre-4.2BSD file sys‐
tem). Debug mode. restore or rrestore performs many internal checks
about the consistency of internal structures and prints debugging
information to the standard output. When an argument follows the -f
modifier flag, it is used as the name of the archive device, replacing
the default tape device /dev/tape/tape0_d1. When the argument is the
character - (dash), restore or rrestore reads from standard input.
Thus, dump and restore or rdump and rrestore may be used in a pipeline
expression to copy file systems with the following typical command:
dump -0f - /usr | (cd /mnt; restore -xf -) The argument that
follows the -F modifier flag is used as the name of the file from which
interactive input is read. As described in the foregoing list of Func‐
tion Flags for the -i function option, normally standard input is read.
The -F modifier flag allows the interactive mode of the restore or
rrestore command to be obtained from a previously written command file
(similar to a shell script).
In the application described here, the following are affected:
The interactive interface A prompt for the next volume number A
prompt to set the access mode for (dot)
Error recovery interaction and the verification of operator
readiness are not affected. For example, if the file named
inputfile contains the following interactive command lines (the
commands are taken from the Function Flags list):
add delete foo add foo/bar extract 1 yes quit
issuing the command: restore -iF inputfile
uses the interactive mode to automatically mark everything for
reading (add), to unmark the subdirectory (delete foo), to mark
the file foo/bar (add foo/bar), to read the marked files
(extract), to specify volume 1 (1) of the default tape, to set
the access mode for dot, (yes), and then quit (quit). Use this
modifier to restore files to a specific directory level. The
specific directory level is the file name defined by the -x
switch or the -t switch (when using command mode) or a file name
in the argument list of the add or the delete command (when
using interactive mode). Files in the named directory that are
directories are not restored. Thus, you can use this modifier
to prevent hierarchical restoration of complete subtrees. When
this modifier is specified, restore or rrestore reads according
to inode numbers rather than filename. This read operation is
useful when only a few files are restored and you want to avoid
rewriting the complete pathname to each file. Tells restore not
to write to disk. This option does not permit the process to
act on files in the current directory. The argument that fol‐
lows this modifier flag is used as the number (1 is the origin)
of the file to restore. This option is used to write more than
one dump file from the tape. Normally the restore or rrestore
commands do not notify you about their progress in reading from
the storage device. When this modifier option is used, the name
of each file read from the tape is written to the standard out‐
put device. When this modifier is specified, restore or
rrestore does not query whether a tape error should cause the
read operation to abort, but instead the process attempts to
skip over the bad block(s) and continue the read operation.
Overwrites the existing files and links without any query. When
this flag is used, the restore or rrestore does not overwrite
existing files.
DESCRIPTION
The restore and rrestore commands are used to read files and associated
extended attributes (including ACLs, see the acl(4) and proplist(4)
reference pages), from a local or remote file system backup (respec‐
tively). The file system backup must have been written by the dump or
rdump command. The restore and rrestore commands only read files to
local file systems.
restore
The options bcdfhimrstvxyFNRYZ consist of function options and modifier
flags, which may be used in any logical combination, but with a preced‐
ing - (dash) character. Each group of options contains at most one
function option and possibly one or more modifier flags. Function
options are irtx and R; all other options are modifier options. Other
arguments specified with these commands are the file or subdirectory
name that specifies files to be restored. The function options and
modifier flags are described under OPTIONS.
Unless the -h modifier flag is specified (see the -h flag), inclusion
of a directory name refers to all files and recursively, all files in
all subdirectories of that directory.
rrestore
The rrestore command reads files from a remote magnetic tape or other
specified storage device. The files were previously saved to tape with
a dump or rdump command. The rrestore command is identical in opera‐
tion to restore, except the -f function option must be specified, and
the dump_file parameter must have the form: machine:device
If you want to specify an IPv6 address for machine, you must prefix the
address with the \[ (backslash, left bracket) characters and terminate
the address with the \] (backslash, right bracket) characters. Because
the bracket characters are shell metacharacters, your must precede them
with the backslash character.
The rrestore command starts remote server /usr/sbin/rmt on the client
machine to access the storage medium.
NOTES
Do not use the restore or rrestore commands to extract an archive on an
AdvFS filesystem.
The restore or rrestore process may become confused when doing incre‐
mental reads from tapes that were previously written from an active
file system.
A level 0 (zero) tape dump or rdump must be done after a full restore.
Because restore or rrestore runs without kernel privileges, it has no
control over inode allocation; thus, a full restore must be done to get
a new set of directories that reflect new inode numbering, even when
the content of files are unchanged.
When the -Y flag is specified, all files, including hard and symbolic
links, are overwritten. When the -Y flag is not specified, hard and
symbolic links are not overwritten, as in previous releases.
Attempting to do a restore/rrestore to a base directory that has a
default ACL or a default access ACL may cause unintended ACLs to be
created on the restored files and directories. If ACLs are enabled on
the system, check all ACLs after the restore/rrestore.
DIAGNOSTICS
Detects bad option characters.
Detects read errors. When the -y modifier flag has been specified, or
you respond with y, the process attempts to continue the restore opera‐
tion.
When a previous dump or rdump writes over more than one storage device,
restore or rrestore asks you to change a filled volume.
When the -x or -i function option has been specified, restore or
rrestore also asks what volume you wish to mount. Note, the restore -x
command is silent if a pipe or a regular file is involved.
A fast way to read a few files is to first mount the last volume, and
then mount other previous volumes working toward the first volume.
There are numerous consistency checks that can be listed by restore.
Most checks are self-explanatory.
Common Errors
Common errors are listed as follows: A tape previously written from an
old file system has been loaded. On reading, the old file system was
automatically converted to a new filesystem format. One or more file‐
names specified by the filename parameter was listed in the tape direc‐
tory, but was not found on the tape. This is caused by storage device
read errors when searching for a named file, or when a previously writ‐
ten tape was created on an active file system. A file that was not
listed in the directory was detected. This can occur when using a tape
previously created on an active file system. When doing incremental
restore, a tape that was written before the previous incremental tape,
or one that has too low an incremental level has been loaded. When
doing incremental restore or rrestore, a storage process does not begin
its coverage where the previous incremental tape left off, or one that
has too high an incremental level has been loaded. A tape read error
has occurred. When a filename is specified, its contents are probably
partially wrong. When an inode is being skipped, or the tape is trying
to resynchronize, no files read from tape have been corrupted although
some files may not be found on the tape. After a tape read error,
restore or rrestore may have to resynchronize itself. This message
lists the number of blocks that were skipped.
FILES
Specifies the command path Specifies the command path The default stor‐
age device. A file that lists directories stored on the default tape.
Owner, permission mode, and timestamps for stored directories. Holds
information required during incremental restore or rrestore operations.
The file is created in the current working directory and is appended
with the node identifier of the cluster member, such as
SEE ALSO
Commands: dump(8), rdump(8), mount(8), umount(8), newfs(8)
Files: acl(4), proplist(4)restore(8)