ufsrestore(1M)
NAME
ufsrestore - incremental file system restore
SYNOPSIS
/usr/sbin/ufsrestore i | r | R | t | x [abcdfhlmostvyLT]
[archive_file] [factor] [dumpfile] [n] [label] [timeout] [
filename...]
DESCRIPTION
The ufsrestore utility restores files from backup media
created with the ufsdump command. ufsrestores's actions are
controlled by the key argument. The key is exactly one func-
tion letter (i, r, R , t, or x) and zero or more function
modifiers (letters). The key string contains no SPACE char-
acters. Function modifier arguments are listed on the com-
mand line in the same order as their corresponding function
modifiers appear in the key string.
filename arguments which appear on the command line, or as
arguments to an interactive command, are treated as shell
glob patterns by the x and t functions; any files or direc-
tories matching the patterns are selected. The metacharac-
ters *, ?, and [ ] must be protected from the shell if they
appear on the command line. There is no way to quote these
metacharacters to explicitly match them in a filename.
The temporary files rstdir* and rstmode* are placed in /tmp
by default. If the environment variable TMPDIR is defined
with a non-empty value, that location is used instead of
/tmp.
OPTIONS
Function Letters
You must specify one (and only one) of the function letters
listed below. Note that i, x, and r are intended to restore
files into an empty directory. The R function is intended
for restoring into a populated directory.
i Interactive. After reading in the directory informa-
tion from the media, ufsrestore invokes a shell-like
interface that allows you to browse through the dump
file's directory hierarchy and select individual files
to be extracted. Restoration has the same semantics as
x (see below). See Interactive Commands, below, for a
description of available commands.
r Recursive. Starting with an empty directory and a
level 0 dump, the r function recreates the filesystem
relative to the current working directory, exactly as
it appeared when the dump was made. Information used
to restore incremental dumps on top of the full dump
(for example, restoresymtable) is also included.
Several ufsrestore runs are typical, one for each
higher level of dump (0, 1, ..., 9). Files that were
deleted between the level 0 and a subsequent incremen-
tal dump will not exist after the final restore. To
completely restore a file system, use the r function
restore the level 0 dump, and again for each incremen-
tal dump. Although this function letter is intended
for a complete restore onto a new file system (one
just created with newfs(1M)), if the file system con-
tains files not on the backup media, they are
preserved.
R Resume restoring. If an r-mode ufsrestore was inter-
rupted, this function prompts for the volume from
which to resume restoring and continues the restora-
tion from where it was left off. Otherwise identical
to r.
t Table of contents. List each filename that appears on
the media. If no filename argument is given, the root
directory is listed. This results in a list of all
files on the media, unless the h function modifier is
in effect. The table of contents is taken from the
media or from the specified archive file, when the a
function modifier is used. The a function modifier is
mutually exclusive with the x and r function letters.
x Extract the named files from the media. Files are
restored to the same relative locations that they had
in the original file system.
If the filename argument matches a directory whose
contents were written onto the media, and the h modif-
ier is not in effect, the directory is recursively
extracted, relative to the current directory, which is
expected to be empty. For each file, the owner, modif-
ication time, and mode are restored (if possible).
If you omit the filename argument or specify ., the
root directory is extracted. This results in the
entire tape being extracted, unless the h modifier is
in effect. . With the x function, existing files are
overwritten and ufsrestore displays the names of the
overwritten files. Overwriting a currently-running
executable can have unfortunate consequences.
Use the x option to restore partial file system dumps,
as they are (by definition) not entire file systems.
Function Modifiers
a archive_file
Read the table of contents from archive_file instead
of the media. This function modifier can be used in
combination with the t, i, or x function letters, mak-
ing it possible to check whether files are on the
media without having to mount the media. When used
with the x and interactive (i) function letters, it
prompts for the volume containing the file(s) before
extracting them.
b factor
Blocking factor. Specify the blocking factor for tape
reads. For variable length SCSI tape devices, unless
the data was written with the default blocking factor,
a blocking factor at least as great as that used to
write the tape must be used; otherwise, an error will
be generated. Note that a tape block is 512 bytes.
Refer to the man page for your specific tape driver
for the maximum blocking factor.
c Convert the contents of the media in 4.1BSD format to
the new ufs file system format.
d Debug. Turn on debugging output.
f dump_file
Use dump_file instead of /dev/rmt/0 as the file to
restore from. Typically dump_file specifies a tape or
diskette drive. If dump_file is specified as `-',
ufsrestore reads from the standard input. This allows
ufsdump(1M) and ufsrestore to be used in a pipeline to
copy a file system:
example# ufsdump 0f - /dev/rdsk/c0t0d0s7 \
| (cd /home;ufsrestore xf -)
If the name of the file is of the form machine:device,
the restore is done from the specified machine over
the network using rmt(1M). Since ufsrestore is nor-
mally run by root, the name of the local machine must
appear in the /.rhosts file of the remote machine. If
the file is specified as user@machine:device, ufsre-
store will attempt to execute as the specified user on
the remote machine. The specified user must have a
.rhosts file on the remote machine that allows the
user invoking the command from the local machine to
access the remote machine.
h Extract or list the actual directory, rather than the
files that it references. This prevents hierarchical
restoration of complete subtrees from the tape.
l Autoload. When the end-of-tape is reached before the
restore is complete, take the drive off-line and wait
up to two minutes (the default, see the T function
modifier) for the tape drive to be ready again. This
gives autoloading (stackloader) tape drives a chance
to load a new tape. If the drive is ready within two
minutes, continue. If it is not, prompt for another
tape and wait.
L label
The label that should appear in the header of the dump
file. If the labels do not match, ufsrestore issues a
diagnostic and exits. The tape label is specific to
the ufsdump tape format, and bears no resemblance to
IBM or ANSI-standard tape labels.
m Extract by inode numbers rather than by filename to
avoid regenerating complete pathnames. Regardless of
where the files are located in the dump hierarchy,
they are restored into the current directory and
renamed with their inode number. This is useful if
only a few files are being extracted.
o Offline. Take the drive off-line when the restore is
complete or the end-of-media is reached and rewind the
tape, or eject the diskette. In the case of some auto-
loading 8mm drives, the tape is removed from the drive
automatically.
s n Skip to the n'th file when there are multiple dump
files on the same tape. For example, the command:
example# ufsrestore xfs /dev/rmt/0hn 5
would position you to the fifth file on the tape when
reading volume 1 of the dump. If a dump extends over
more than one volume, all volumes except the first are
assumed to start at position 0, no matter what "s n"
value is specified.
If "s n" is specified, the backup media must be at BOT
(beginning of tape). Otherwise, the initial position-
ing to read the table of contents will fail, as it is
performed by skipping the tape forward n-1 files
rather than by using absolute positioning. This is
because on some devices absolute positioning is very
time consuming.
T timeout [hms]
Sets the amount of time to wait for an autoload com-
mand to complete. This function modifier is ignored
unless the l function modifier has also been speci-
fied. The default timeout period is two minutes. The
time units may be specified as a trailing h (hours), m
(minutes), or s (seconds). The default unit is
minutes.
v Verbose. ufsrestore displays the name and inode number
of each file it restores, preceded by its file type.
y Do not ask whether to abort the restore in the event
of tape errors. ufsrestore tries to skip over the bad
tape block(s) and continue as best it can.
Interactive Commands
ufsrestore enters interactive mode when invoked with the i
function letters. Interactive commands are reminiscent of
the shell. For those commands that accept an argument, the
default is the current directory. The interactive options
are:
add [filename]
Add the named file or directory to the list of files
to extract. If a directory is specified, add that
directory and its files (recursively) to the extrac-
tion list (unless the h modifier is in effect).
cd directory
Change to directory (within the dump file).
delete [filename]
Delete the current directory, or the named file or
directory from the list of files to extract. If a
directory is specified, delete that directory and all
its descendents from the extraction list (unless the h
modifier is in effect). The most expedient way to
extract a majority of files from a directory is to add
that directory to the extraction list, and then delete
specific files to omit.
extract
Extract all files on the extraction list from the dump
media. ufsrestore asks which volume the user wishes to
mount. The fastest way to extract a small number of
files is to start with the last volume and work toward
the first. If "s n" is given on the command line,
volume 1 will automatically be positioned to file n
when it is read.
help Display a summary of the available commands.
ls [directory]
List files in directory or the current directory,
represented by a `.' (period). Directories are
appended with a `/' (slash). Entries marked for
extraction are prefixed with a `*' (asterisk). If the
verbose option is in effect, inode numbers are also
listed.
marked [directory]
Like ls, except only files marked for extraction are
listed.
pager Toggle the pagination of the output from the ls and
marked commands. The pager used is that defined by the
PAGER environment variable, or more(1) if that envar
is not defined. The PAGER envar may include white-
space-separated arguments for the pagination program.
pwd Print the full pathname of the current working direc-
tory.
quit ufsrestore exits immediately, even if the extraction
list is not empty.
setmodes
Prompts: set owner/mode for `.' (period). Type y for
yes to set the mode (permissions, owner, times) of the
current directory `.' (period) into which files are
being restored equal to the mode of the root directory
of the file system from which they were dumped. Nor-
mally, this is what you want when restoring a whole
file system, or restoring individual files into the
same locations from which they were dumped. Type n for
no, to leave the mode of the current directory
unchanged. Normally, this is what you want when res-
toring part of a dump to a directory other than the
one from which the files were dumped.
setpager command
Sets the command to use for paginating output instead
of the default or that inherited from the environment.
The command string may include arguments in addition
to the command itself.
verbose
Toggle the status of the v modifier. While v is in
effect, the ls command lists the inode numbers of all
entries, and ufsrestore displays information about
each file as it is extracted.
what Display the dump header on the media.
OPERANDS
The following operands are supported.
filename
Specifies the pathname of files (or directories) to be
restored to disk. Unless the h function modifier is
also used, a directory name refers to the files it
contains, and (recursively) its subdirectories and the
files they contain. filename is associated with either
the x or t function letters, and must come last.
USAGE
See largefile(5) for the description of the behavior of
ufsrestore when encountering files greater than or equal to
2 Gbyte ( 2**31 bytes).
EXIT STATUS
The following exit values are returned:
0 Successful completion.
1 An error occurred. Verbose messages are displayed.
ENVIRONMENT VARIABLES
PAGER The command to use as a filter for paginating output.
This can also be used to specify the options to be
used. Default is more(1).
TMPDIR
Selects the directory for temporary files. Defaults to
/tmp if not defined in the environment.
FILES
/dev/rmt/0
the default tape drive
$TMPDIR/rstdir*
file containing directories on the tape
$TMPDIR/rstmode*
owner, mode, and timestamps for directories
./restoresymtable
information passed between incremental restores
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWcsu |
|_____________________________|_____________________________|
SEE ALSO
more(1), mkfs(1M), mount(1M), rmt(1M), ufsdump(1M), attri-
butes(5), largefile(5)
DIAGNOSTICS
ufsrestore complains about bad option characters.
Read errors result in complaints. If y has been specified,
or the user responds y, ufsrestore will attempt to continue.
If the dump extends over more than one tape, ufsrestore asks
the user to change tapes. If the x or i function letter has
been specified, ufsrestore also asks which volume the user
wishes to mount. If the s modifier has been specified, and
volume 1 is mounted, it is automatically positioned to the
indicated file.
There are numerous consistency checks that can be listed by
ufsrestore. Most checks are self-explanatory or can "never
happen". Common errors are given below.
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.
filename: not found on tape
The specified file name was listed in the tape direc-
tory, but was not found on the tape. This is caused by
tape read errors while looking for the file, using a
dump tape created on an active file system, or restor-
ing a partial dump with the r function.
expected next file inumber, got inumber
A file that was not listed in the directory showed up.
This can occur when using a dump tape created on an
active file system.
Incremental tape too low
When doing an incremental restore, a tape that was
written before the previous incremental tape, or that
has too low an incremental level has been loaded.
Incremental tape too high
When doing incremental restore, a tape that does not
begin its coverage where the previous incremental tape
left off, or one that has too high an incremental
level has been loaded.
media read error: invalid argument
Blocking factor specified for read is smaller than the
blocking factor used to write data.
Tape read error while restoring
Tape read error while skipping over inode inumber
Tape read error while trying to resynchronize
A tape 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.
resync ufsrestore, skipped num
After a tape read error, ufsrestore may have to resyn-
chronize itself. This message lists the number of
blocks that were skipped over.
Incorrect tape label. Expected `foo', got `bar'.
The L option was specified, and its value did not
match what was recorded in the header of the dump
file.
NOTES
ufsrestore can get confused when doing incremental restores
from dump tapes that were made on active file systems.
A level 0 dump must be done after a full restore. Because
ufsrestore runs in user mode, it has no control over inode
allocation. This means that ufsrestore repositions the
files, although it does not change their contents. Thus, a
full dump must be done to get a new set of directories
reflecting the new file positions, so that later incremental
dumps will be correct.
Man(1) output converted with
man2html