ufsrestore - incremental file system restore
/usr/sbin/ufsrestore i | r | R | t | x [abcdfhlmostvyLT]
[archive_file] [factor] [dumpfile] [n] [label]
[timeout] [filename]...
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 command 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.
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 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 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 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(8)), if the file system
contains 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 directory, 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, 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.
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 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(8)
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(8). 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 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 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 command
to complete. This function modifier is ignored unless the l function
modifier has also been specified. 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.
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 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
directory.
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. Normally, 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 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 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.
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.
See largefile(7) for the description of the behavior of
ufsrestore when encountering files greater than or equal to 2 Gbyte
(2^31 bytes).
The following exit values are returned:
0
Successful completion.
1
An error occurred. Verbose messages are displayed.
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.
/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
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 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 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
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.
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.