Unix‎ > ‎Solaris‎ > ‎Solaris man pages‎ > ‎1m‎ > ‎

ufsrestore


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 information
          from  the media, ufsrestore invokes a shell-like inter-
          face 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 descrip-
          tion 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  com-
          plete  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  inter-
          rupted, 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 con-
          tents  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, modifi-
          cation 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 exe-
          cutable 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 combina-
                        tion   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  con-
                        taining  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 gen-
                        erated.  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 sys-
                        tem:

                          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 modif-
                        ier) for  the  tape  drive  to  be  ready
                        again.  This  gives  autoloading  (stack-
                        loader) 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 nth file when there are  mul-
                        tiple  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). Oth-
                        erwise, 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 dev-
                        ices  absolute  positioning  is very time
                        consuming.


     T timeout [hms]    Sets the amount of time to  wait  for  an
                        autoload  command to complete. This func-
                        tion 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 direc-
                           tory 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  extrac-
                           tion 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  com-
                           mand 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 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 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 out-
               put.  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 environ-
               ment.



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),  ufs-
     dump(4), 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 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.










Man pages from Solaris 10 Update 8. See docs.sun.com and www.oracle.com for further documentation and Solaris information.
Comments