System Administration Commands 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 infor-
mation 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 Interac-
tive Commands, below, for a description of avail-
able commands.
r Recursive. Starting with an empty directory and a
level 0 dump, the r function recreates the filesys-
tem 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 typi-
cal, 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(1M)), 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 recur-
sively 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, existing files
are overwritten and ufsrestore displays the names
of the overwritten files. Overwriting a currently-
running executable can have unfortunate conse-
quences.
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 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 max-
imum 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 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 com-
plete 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 resem-
blance 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 n'th file when there are multi-
ple dump files on the same tape. For exam-
ple, 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 auto-
load 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, pre-
ceded 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 con-
tinue 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 (recur-
sively) 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 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 ver-
bose 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 direc-
tory 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 paginat-
ing 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
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 direc-
tories) 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 paginat-
ing 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 incremen-
tal 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 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 writ-
ten 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 prob-
ably 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.
|
|
