ufsrestore(1M)                                            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 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.

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 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 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(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  sys-
                tem.

                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.

   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 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 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  min-
                       utes  (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 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 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 posi-
                       tioning. 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  func-
                       tion  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.

   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 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 sys-
                               tem 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 cur-
                               rent 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.

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 attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE         |      ATTRIBUTE VALUE        |
       +-----------------------------+-----------------------------+
       |Availability                 |SUNWcsu                      |
       +-----------------------------+-----------------------------+

SEE ALSO

       more(1), mkfs(1M), mount(1M), rmt(1M), ufsdump(1M), attributes(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 automati-
       cally 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 look-
           ing 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.

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.

SunOS 5.10                                                          24 Sep 2002                                                     ufsrestore(1M)