xfsrestore(1M)                                                  xfsrestore(1M)

NAME
     xfsrestore - XFS filesystem incremental restore utility

SYNOPSIS
     xfsrestore [ -a housekeeping ] [ -e ] [ -f source ... ]
           [ -i ] [ -n file ] [ -o ] [ -p report_interval ] [ -r ]
           [ -s subtree ... ] [ -t ] [ -v verbosity ] [ -A ] [ -D ]
           [ -E ] [ -I [ subopt=value ... ] ] [ -J ] [ -L session_label ]
           [ -O options_file ] [ -Q ] [ -R ] [ -S session_id ] [ -T ]
           [ -Y io_ring_length ] [ - ] destination

DESCRIPTION
     xfsrestore restores filesystems from dumps produced by xfsdump(1M).  Two
     modes of operation are available:  simple and cumulative.

     The default is simple mode.  xfsrestore populates the specified
     destination directory, destination, with the files contained in the dump
     media.

     The -r option specifies the cumulative mode.  Successive invocations of
     xfsrestore are used to apply a chronologically ordered sequence of delta
     dumps to a base (level 0) dump.  The contents of the filesystem at the
     time each dump was produced is reproduced.  This can involve adding,
     deleting, renaming, linking, and unlinking files and directories.

     A delta dump is defined as either an incremental dump (xfsdump -l option
     with level > 0) or a resumed dump (xfsdump -R option).  The deltas must
     be applied in the order they were produced.  Each delta applied must have
     been produced with the previously applied delta as its base.

     -a housekeeping
          Each invocation of xfsrestore creates a directory called
          xfsrestorehousekeepingdir.  This directory is normally created
          directly under the destination directory.  The -a option allows the
          operator to specify an alternate directory, housekeeping, in which
          xfsrestore creates the xfsrestorehousekeeping directory.  When
          performing a cumulative (-r option) restore, each successive
          invocation of xfsrestore must specify the same alternate directory.

     -e   Prevents xfsrestore from overwriting existing files in the
          destination directory.

     -f source
          Specifies a source of the dump to be restored.  This can be the
          pathname of a device (such as a tape drive), a regular file, or a
          remote tape drive (see rmt(1M)).  Up to 20 sources can be specified.
          All sources are simultaneously applied to the restore.  For example,
          if the dump to be restored spanned three tapes, three tape drives
          could be used to simultaneously restore the portions of the dump
          contained on each tape.  All other permutations are supported.  This
          option must be omitted if the standard input option (a lone -
          preceding the destination specification) is specified.

                                                                        Page 1

xfsrestore(1M)                                                  xfsrestore(1M)

     -i   Selects interactive operation.  Once the on-media directory
          hierarchy has been read, an interactive dialogue is begun.  The
          operator uses a small set of commands to peruse the directory
          hierarchy, selecting files and subtrees for extraction.  The
          available commands are given below.  Initially nothing is selected,
          except for those subtrees specified with -s command line options.

          ls [arg]       List the entries in the current directory or the
                         specified directory, or the specified non-directory
                         file entry.  Both the entry's original inode number
                         and name are displayed.  Entries that are directories
                         are appended with a `/'.  Entries that have been
                         selected for extraction are prepended with a `*'.

          cd [arg]       Change the current working directory to the specified
                         argument, or to the filesystem root directory if no
                         argument is specified.

          pwd            Print the pathname of the current directory, relative
                         to the filesystem root.

          add [arg]      The current directory or specified file or directory
                         within the current directory is selected for
                         extraction.  If a directory is specified, then it and
                         all its descendents are selected.  Entries that are
                         selected for extraction are prepended with a `*' when
                         they are listed by ls.

          delete [arg]   The current directory or specified file or directory
                         within the current directory is deselected for
                         extraction.  If a directory is specified, then it and
                         all its descendents are deselected.  The most
                         expedient way to extract most of the files from a
                         directory is to select the directory and then
                         deselect those files that are not needed.

          extract        Ends the interactive dialogue, and causes all
                         selected subtrees to be restored.

          quit           xfsrestore ends the interactive dialogue and
                         immediately exits, even if there are files or
                         subtrees selected for extraction.

          help           List a summary of the available commands.

     -n file
          Allows xfsrestore to restore only files newer than file.  The
          modification time of file (i.e., as displayed with the ls -l
          command) is compared to the inode modification time of each file on
          the source media (i.e., as displayed with the ls -lc command).  A
          file is restored from media only if its inode modification time is
          greater than or equal to the modification time of file.
                                                                        Page 2

xfsrestore(1M)                                                  xfsrestore(1M)

     -o   Restore file and directory owner/group even if not root.  When run
          with an effective user id of root, xfsrestore restores owner and
          group of each file and directory.  When run with any other effective
          user id it does not, unless this option is specified.

     -r   Selects the cumulative mode of operation.

     -s subtree
          Specifies a subtree to restore.  Any number of -s options are
          allowed.  The restore is constrained to the union of all subtrees
          specified.  Each subtree is specified as a pathname relative to the
          restore destination.  If a directory is specified, the directory and
          all files beneath that directory are restored.

     -t   Displays the contents of the dump, but does not create or modify any
          files or directories.  It may be desirable to set the verbosity
          level to silent when using this option.

     -v verbosity_level
          Specifies the level of detail of the messages displayed during the
          course of the restore.  The argument can be silent, verbose, or
          trace.  The default is verbose.

     -A   Do not restore extended file attributes.  If this option is not
          specified, extended file attributes are restored.  Note that dumping
          of extended file attributes is also optional.

     -D   Restore DMAPI (Data Management Application Programming Interface)
          event settings.  xfsdump backs backs up these settings, but it is
          usually not desirable to restore them.

     -E   Prevents xfsrestore from overwriting newer versions of files.  The
          inode modification time of the on-media file is compared to the
          inode modification time of corresponding file in the destination
          directory.  The file is restored only if the on-media version is
          newer than the version in the destination directory.  The inode
          modification time of a file can be displayed with the ls -lc
          command.

     -I   Causes the xfsdump inventory to be displayed (no restore is
          performed).  Each time xfsdump is used, an online inventory in
          /var/xfsdump/inventory is updated.  This is used to determine the
          base for incremental dumps.  It is also useful for manually
          identifying a dump session to be restored (see the -L and -S
          options).  Suboptions to filter the inventory display are described
          later.

     -J   Inhibits inventory update when on-media session inventory
          encountered during restore.  xfsrestore opportunistically updates
          the online inventory when it encounters an on-media session
          inventory, but only if run with an effective user id of root and
          only if this option is not given.

                                                                        Page 3

xfsrestore(1M)                                                  xfsrestore(1M)

     -L session_label
          Specifies the label of the dump session to be restored.  The source
          media is searched for this label.  It is any arbitrary string up to
          255 characters long.  The label of the desired dump session can be
          copied from the inventory display produced by the -I option.

     -O options_file
          Insert the options contained in options_file into the beginning of
          the command line.  The options are specified just as they would
          appear if typed into the command line.  In addition, newline
          characters (\n) can be used as whitespace.  The options are placed
          before all options actually given on the command line, just after
          the command name.  Only one -O option can be used.  Recursive use is
          ignored.  The destination directory cannot be specified in
          options_file.

     -Q   Force completion of an interrupted restore session.  This option is
          required to work around one specific pathological scenario.  When
          restoring a dump session which was interrupted due to an EOM
          condition and no online session inventory is available, xfsrestore
          cannot know when the restore of that dump session is complete.  The
          operator is forced to interrupt the restore session.  In that case,
          if the operator tries to subsequently apply a resumed dump (using
          the -r option), xfsrestore refuses to do so.  The operator must tell
          xfsrestore to consider the base restore complete by using this
          option when applying the resumed dump.

     -R   Resume a previously interrupted restore.  xfsrestore can be
          interrupted at any time by pressing the terminal interrupt character
          (see stty(1)).  Use this option to resume the restore.  The -a and
          destination options must be the same.

     -S session_id
          Specifies the session UUID of the dump session to be restored.  The
          source media is searched for this UUID.  The UUID of the desired
          dump session can be copied from the inventory display produced by
          the -I option.

     -T   Inhibits interactive dialogue timeouts.  xfsrestore prompts the
          operator for media changes.  This dialogue normally times out if no
          response is supplied.  This option prevents the timeout.

     -X subtree
          Specifies a subtree to exclude.  This is the converse of the -s
          option.  Any number of -X options are allowed.  Each subtree is
          specified as a pathname relative to the restore destination.  If a
          directory is specified, the directory and all files beneath that
          directory are excluded.

     -Y io_ring_length
          Specify I/O buffer ring length.  xfsrestore uses a ring of input
          buffers to achieve maximum throughput when restoring from tape

                                                                        Page 4

xfsrestore(1M)                                                  xfsrestore(1M)

          drives.  The default ring length is 3.

     -    A lone - causes the standard input to be read as the source of the
          dump to be restored.  Standard input can be a pipe from another
          utility (such as xfsdump(1M)) or a redirected file.  This option
          cannot be used with the -f option.  The - must follow all other
          options, and precede the destination specification.

     The dumped filesystem is restored into the destination directory.  There
     is no default; the destination must be specified.

NOTES
   Cumulative Restoration
     A base (level 0) dump and an ordered set of delta dumps can be
     sequentially restored, each on top of the previous, to reproduce the
     contents of the original filesystem at the time the last delta was
     produced.  The operator invokes xfsrestore once for each dump.  The -r
     option must be specified.  The destination directory must be the same for
     all invocations.  Each invocation leaves a directory named
     xfsrestorehousekeeping in the destination directory (however, see the -a
     option above).  This directory contains the state information that must
     be communicated between invocations.  The operator must remove this
     directory after the last delta has been applied.

     xfsrestore also generates a directory named orphanage in the destination
     directory.  xfsrestore removes this directory after completing a simple
     restore.  However, if orphanage is not empty, it is not removed.  This
     can happen if files present on the dump media are not referenced by any
     of the restored directories.  The orphanage has an entry for each such
     file.  The entry name is the file's original inode number, a ".", and the
     file's generation count modulo 4096 (only the lower 12 bits of the
     generation count are used).

     xfsrestore does not remove the orphanage after cumulative restores.  Like
     the xfsrestorehousekeeping directory, the operator must remove it after
     applying all delta dumps.

   Media Management
     A dump consists of one or more media files contained on one or more media
     objects.  A media file contains all or a portion of the filesystem dump.
     Large filesystems are broken up into multiple media files to minimize the
     impact of media dropouts, and to accommodate media object boundaries
     (end-of-media).

     A media object is any storage medium:  a tape cartridge, a remote tape
     device (see rmt(1M)), a regular file, or the standard input (currently
     other removable media drives are not supported).  Tape cartridges can
     contain multiple media files, which are typically separated by (in tape
     parlance) file marks.  If a dump spans multiple media objects, the
     restore must begin with the media object containing the first media file
     dumped.  The operator is prompted when the next media object is needed.

                                                                        Page 5

xfsrestore(1M)                                                  xfsrestore(1M)

     Media objects can contain more than one dump.  The operator can select
     the desired dump by specifying the dump label (-L option), or by
     specifying the dump UUID (-S option).  If neither is specified,
     xfsrestore scans the entire media object, prompting the operator as each
     dump session is encountered.

     The inventory display (-I option) is useful for identifying the media
     objects required.  It is also useful for identifying a dump session.  The
     session UUID can be copied from the inventory display to the -S option
     argument to unambiguously identify a dump session to be restored.

     Dumps placed in regular files or the standard output do not span multiple
     media objects, nor do they contain multiple dumps.

   Inventory
     Each dump session updates an inventory database in
     /var/xfsdump/inventory.  This database can be displayed by invoking
     xfsrestore with the -I option.  The display uses tabbed indentation to
     present the inventory hierarchically.  The first level is filesystem.
     The second level is session.  The third level is media stream (currently
     only one stream is supported).  The fourth level lists the media files
     sequentially composing the stream.

     Several suboptions are available to filter the display.  Specifying -I
     depth=n (where n is 1, 2, or 3) limits the hierarchical depth of the
     display.  Specifying -I mobjid=value (where value is a media id) or -I
     mobjlabel=value (where value is a media label) limits the display to
     media files contained in the specified media object.  Similarly, the
     display can be restricted to a specific filesystem identified by mount
     point using -I mnt=host-qualified_mount_point_pathname, by filesystem id
     using -I fsid=filesystem_id, or by device using -I dev=host-
     qualified_device_pathname.

     At most three suboptions can be specified at once:  one to constrain the
     depth, one to constrain the media object, and one to constrain the
     filesystem.  For example, -I depth=1,mobjlabel="tape
     1",mnt=host1:/test_mnt displays only the filesystem information (depth=1)
     for those filesystems which were mounted on host1:/test_mnt at the time
     of the dump and only those filesystems dumped to the media object labeled
     "tape 1".

     There is currently no way to remove dumps from the inventory.

     An additional media file is placed at the end of each dump stream.  This
     media file contains the inventory information for the current dump
     session.  This is currently unused.

   Media Errors
     xfsdump is tolerant of media errors, but cannot do error correction.  If
     a media error occurs in the body of a media file, the filesystem file
     represented at that point is lost.  The bad portion of the media is
     skipped, and the restoration resumes at the next filesystem file after

                                                                        Page 6

xfsrestore(1M)                                                  xfsrestore(1M)

     the bad portion of the media.

     If a media error occurs in the beginning of the media file, the entire
     media file is lost.  For this reason, large dumps are broken into a
     number of reasonably sized media files.  The restore resumes with the
     next media file.

FILES
     /var/xfsdump/inventory   dump inventory database

SEE ALSO
     rmt(1M), xfsdump(1M), attr_set(2).

DIAGNOSTICS
     The exit code is 0 on normal completion, and non-zero if an error
     occurred or the restore was terminated by the operator.

BUGS
     Pathnames of restored non-directory files (relative to the destination
     directory) must be 1023 characters (MAXPATHLEN) or less.  Longer
     pathnames are discarded and a warning message displayed.

     There is no verify option to xfsrestore.  This would allow the operator
     to compare a filesystem dump to an existing filesystem, without actually
     doing a restore.

     The interactive commands (-i option) do not understand regular
     expressions.

     Cumulative mode (-r option) requires that the operator invoke xfsrestore
     for the base and for each delta to be applied in sequence to the base.
     It would be better to allow the operator to identify the last delta in
     the sequence of interest, and let xfsrestore work backwards from that
     delta to identify and apply the preceding deltas and base dump, all in
     one invocation.

                                                                        Page 7