xfsrestore(8) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | NOTES | EXAMPLES | FILES | SEE ALSO | DIAGNOSTICS | BUGS | COLOPHON

xfsrestore(8)            System Manager's Manual           xfsrestore(8)

NAME         top

       xfsrestore - XFS filesystem incremental restore utility

SYNOPSIS         top

       xfsrestore -h
       xfsrestore [ options ] -f source [ -f source ... ] dest
       xfsrestore [ options ] - dest
       xfsrestore -I [ subopt=value ... ]

DESCRIPTION         top

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

       The default is simple mode.  xfsrestore populates the specified
       destination directory, dest, 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.

       xfsrestore keeps state information in the
       xfsrestorehousekeepingdir, to inform subsequent invocations when
       used in cumulative mode, or in the event a restore is
       interrupted.  To ensure that the state information can be
       processed, a compatible version of xfsrestore must be used for
       each subsequent invocation. Additionally, each invocation must
       run on a system of the same endianness and page size.

       The options to xfsrestore are:

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

       -b blocksize
            Specifies the blocksize, in bytes, to be used for the
            restore.  For other drives such as DAT or 8 mm , the same
            blocksize used for the xfsdump operation must be specified
            to restore the tape.  The default block size is 1Mb.

       -c progname
            Use the specified program to alert the operator when a media
            change is required. The alert program is typically a script
            to send a mail or flash a window to draw the operator's
            attention.

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

       -f source [ -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(8)).  This option must
            be omitted if the standard input option (a lone - preceding
            the dest specification) is specified.

       -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.

       -m   Use the minimal tape protocol.  This option cannot be used
            without specifying a blocksize to be used (see -b option
            above).

       -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.

       -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.

       -p interval
            Causes progress reports to be printed at intervals of
            interval seconds.  The interval value is approximate,
            xfsrestore will delay progress reports to avoid undue
            processing overhead.

       -q   Source tape drive is a QIC tape.  QIC tapes only use a 512
            byte blocksize, for which xfsrestore must make special
            allowances.

       -r   Selects the cumulative mode of operation. The -a and
            destination options must be the same for each invocation.

       -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 dest.  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
       -v subsys=verbosity[,subsys=verbosity,...]
            Specifies the level of detail used for messages displayed
            during the course of the restore. The verbosity argument can
            be passed as either a string or an integer. If passed as a
            string the following values may be used: silent, verbose,
            trace, debug, or nitty.  If passed as an integer, values
            from 0-5 may be used. The values 0-4 correspond to the
            strings already listed. The value 5 can be used to produce
            even more verbose debug output.

            The first form of this option activates message logging
            across all restore subsystems. The second form allows the
            message logging level to be controlled on a per-subsystem
            basis. The two forms can be combined (see the example
            below). The argument subsys can take one of the following
            values: general, proc, drive, media, inventory, and tree.

            For example, to restore the root filesystem with tracing
            activated for all subsystems:

                 # xfsrestore -v trace -f /dev/tape /

            To enable debug-level tracing for drive and media
            operations:

                 # xfsrestore -v drive=debug,media=debug -f /dev/tape /

            To enable tracing for all subsystems, and debug level
            tracing for drive operations only:

                 # xfsrestore -v trace,drive=debug -f /dev/tape /

       -A   Do not restore extended file attributes.  When restoring a
            filesystem managed within a DMF environment this option
            should not be used. DMF stores file migration status within
            extended attributes associated with each file. If these
            attributes are not preserved when the filesystem is
            restored, files that had been in migrated state will not be
            recallable by DMF. Note that dumping of extended file
            attributes is also optional.

       -B   Change the ownership and permissions of the destination
            directory to match those of the root directory of the dump.

       -D   Restore DMAPI (Data Management Application Programming
            Interface) event settings. If the restored filesystem will
            be managed within the same DMF environment as the original
            dump it is essential that the -D option be used. Otherwise
            it is not usually desirable to restore these settings.

       -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 dest directory.  The file is restored only if
            the on-media version is newer than the version in the dest
            directory.  The inode modification time of a file can be
            displayed with the ls -lc command.

       -F   Inhibit interactive operator prompts.  This option inhibits
            xfsrestore from prompting the operator for verification of
            the selected dump as the restore target and from prompting
            for any media change.

       -I   Causes the xfsdump inventory to be displayed (no restore is
            performed).  Each time xfsdump is used, an online inventory
            in /var/lib/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.

       -K   Force xfsrestore to use dump format 2 generation numbers.
            Normally the need for this is determined automatically, but
            this option is required on the first xfsrestore invocation
            in the rare case that a cumulative restore begins with a
            format 3 (or newer) dump and will be followed by a format 2
            dump.

       -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
            dest.  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 drives.  The default ring length is 3.  However,
            this is not currently enabled on Linux yet, making this
            option benign.

       -    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(8)) or a redirected
            file.  This option cannot be used with the -f option.  The -
            must follow all other options, and precede the dest
            specification.

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

NOTES         top

   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 dest directory
       must be the same for all invocations.  Each invocation leaves a
       directory named xfsrestorehousekeeping in the dest 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 dest
       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(8)), 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.

       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/lib/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.

       The following suboptions are available to filter the display.

       -I depth=n
            (where n is 1, 2, or 3) limits the hierarchical depth of the
            display. When n is 1, only the filesystem information from
            the inventory is displayed. When n is 2, only filesystem and
            session information are displayed. When n is 3, only
            filesystem, session and stream information are displayed.

       -I level=n
            (where n is the dump level) limits the display to dumps of
            that particular dump level.

       The display may be restricted to media files contained in a
       specific media object.

       -I mobjid=value
            (where value is a media ID) specifies the media object by
            its media ID.

       -I mobjlabel=value
            (where value is a media label) specifies the media object by
            its media label.

       Similarly, the display can be restricted to a specific
       filesystem.

       -I mnt=mount_point
            (that is, [hostname:]pathname), identifies the filesystem by
            mountpoint.  Specifying the hostname is optional, but may be
            useful in a clustered environment where more than one host
            can be responsible for dumping a filesystem.

       -I fsid=filesystem_id
            identifies the filesystem by filesystem ID.

       -I dev=device_pathname
            (that is, [hostname:]device_pathname) identifies the
            filesystem by device.  As with the mnt filter, specifying
            the hostname is optional.

       More than one of these suboptions, separated by commas, may be
       specified at the same time to limit the display of the inventory
       to those dumps of interest.  However, at most four suboptions can
       be specified at once: one to constrain the display hierarchy
       depth, one to constrain the dump level, one to constrain the
       media object, and one to constrain the filesystem.

       For example, -I depth=1,mobjlabel="tape 1",mnt=host1:/test_mnt
       would display only the filesystem information (depth=1) for those
       filesystems that were mounted on host1:/test_mnt at the time of
       the dump, and only those filesystems dumped to the media object
       labeled "tape 1".

       Dump records may be removed (pruned) from the inventory using the
       xfsinvutil program.

       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.  If the online inventory files in
       /var/lib/xfsdump/inventory are missing information for the
       current dump session, then the inventory information in the media
       file is automatically added to the files in
       /var/lib/xfsdump/inventory.  If you wish to incorporate the
       inventory information from the media file without restoring any
       data, you may do so using the -t option:

            # xfsrestore -t -f /dev/tape

       This is useful to rebuild the inventory database if it is ever
       lost or corrupted.  The only caveat is that xfsrestore needs to
       read through the entire dump in order to reach the inventory
       media file.  This could become time consuming for dump sessions
       with large media files.

   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 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.

   Quotas
       When xfsdump dumps a filesystem with user quotas, it creates a
       file in the root of the dump called xfsdump_quotas.  xfsrestore
       can restore this file like any other file included in the dump.
       This file can be processed by the restore command of xfs_quota(8)
       to reactivate the quotas.  However, the xfsdump_quotas file
       contains information which may first require modification;
       specifically the filesystem name and the user ids.  If you are
       restoring the quotas for the same users on the same filesystem
       from which the dump was taken, then no modification will be
       necessary.  However, if you are restoring the dump to a different
       filesystem, you will need to:

       - ensure the new filesystem is mounted with the quota option

       - modify the xfsdump_quotas file to contain the new filesystem
              name

       - ensure the uids in the xfsdump_quotas file are correct

       Once the quota information has been verified, the restore command
       of xfs_quota(8) can be used to apply the quota limits to the
       filesystem.

       Group and project quotas are handled in a similar fashion and
       will be restored in files called xfsdump_quotas_group and
       xfsdump_quotas_proj, respectively.

EXAMPLES         top

       To restore the root filesystem from a locally mounted tape:

            # xfsrestore -f /dev/tape /

       To restore from a remote tape, specifying the dump session id:

            # xfsrestore -L session_1 -f otherhost:/dev/tape /new

       To restore the contents a of a dump to another subdirectory:

            # xfsrestore -f /dev/tape /newdir

       To copy the contents of a filesystem to another directory (see
       xfsdump(8)):

            # xfsdump -J - / | xfsrestore -J - /new

FILES         top

       /var/lib/xfsdump/inventory
              dump inventory database

SEE ALSO         top

       rmt(8), xfsdump(8), xfsinvutil(8), xfs_quota(8), attr_set(2).

DIAGNOSTICS         top

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

       For all verbosity levels greater than 0 (silent) the final line
       of the output shows the exit status of the restore. It is of the
       form:

            xfsdump: Restore Status: code

       Where code takes one of the following values: SUCCESS (normal
       completion), INTERRUPT (interrupted), QUIT (media no longer
       usable), INCOMPLETE (restore incomplete), FAULT (software error),
       and ERROR (resource error).  Every attempt will be made to keep
       both the syntax and the semantics of this log message unchanged
       in future versions of xfsrestore.  However, it may be necessary
       to refine or expand the set of exit codes, or their
       interpretation at some point in the future.

BUGS         top

       Pathnames of restored non-directory files (relative to the dest
       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.

       When the minimal rmt option is specified, xfsrestore applies it
       to all remote tape sources. The same blocksize (specified by the
       -b option) is used for all these remote drives.

       xfsrestore uses the alert program only when a media change is
       required.

       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.

COLOPHON         top

       This page is part of the xfsdump (XFS dump and restore) project.
       Information about the project can be found at ⟨http://xfs.org/⟩.
       If you have a bug report for this manual page, send it to
       [email protected].  This page was obtained from the
       project's upstream Git repository
       ⟨https://git.kernel.org/pub/scm/fs/xfs/xfsprogs-dev.git⟩ on
       2024-06-14.  (At that time, the date of the most recent commit
       that was found in the repository was 2022-12-15.)  If you
       discover any rendering problems in this HTML version of the page,
       or you believe there is a better or more up-to-date source for
       the page, or you have corrections or improvements to the
       information in this COLOPHON (which is not part of the original
       manual page), send a mail to [email protected]

                                                           xfsrestore(8)

Pages that refer to this page: xfs(5)xfs_copy(8)xfsdump(8)xfsinvutil(8)