UFSRESTORE(1M)UFSRESTORE(1M)NAMEufsrestore - 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 function letter (i, r, R , t, or x)
and zero or more function modifiers (letters). The key string contains
no SPACE characters. 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 directories matching the patterns are
selected. The metacharacters *, ?, 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 popu‐
lated directory.
i
Interactive. After reading in the directory information 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 seman‐
tics 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 ufs‐
restore runs are typical, one for each higher level of dump (0, 1,
..., 9). Files that were deleted between the level 0 and a subse‐
quent incremental 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 incremental 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 interrupted, this
function prompts for the volume from which to resume restoring and
continues the restoration 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 modifier is not in effect, the
directory is recursively extracted, relative to the current direc‐
tory, which is expected to be empty. For each file, the owner,
modification 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, exist‐
ing 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,
making 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 block‐
ing 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 spe‐
cific 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 speci‐
fied machine over the network using rmt(1M). Since
ufsrestore is normally 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, ufsrestore will attempt to exe‐
cute 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 hierar‐
chical 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 func‐
tion 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
autoloading 8mm drives, the tape is removed from the
drive automatically.
s n
Skip to the nth 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
positioning 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 num‐
ber 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 extraction 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 direc‐
tory 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 automat‐
ically 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
directory.
quit
ufsrestore exits immediately, even if the extrac‐
tion 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. Normally, this is
what you want when restoring a whole file system,
or restoring individual files into the same loca‐
tions 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
restoring 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 argu‐
ments 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 informa‐
tion 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 con‐
tain. filename is associated with either the x or t func‐
tion 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
SEE ALSOmore(1), mkfs(1M), mount(1M), rmt(1M), ufsdump(1M), ufsdump(4),
attributes(5), largefile(5)DIAGNOSTICSufsrestore 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, ufs‐
restore also asks which volume the user wishes to mount. If the s modi‐
fier 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 directory, 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 restoring 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 cov‐
erage 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 par‐
tially 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 resynchronize
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.
NOTESufsrestore 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 incremen‐
tal dumps will be correct.
Sep 24, 2002 UFSRESTORE(1M)
