xfsdump(8) — Linux manual page

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

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

NAME         top

       xfsdump - XFS filesystem incremental dump utility

SYNOPSIS         top

       xfsdump -h
       xfsdump [ options ] -f dest [ -f dest ... ] filesystem
       xfsdump [ options ] - filesystem
       xfsdump -I [ subopt=value ... ]

DESCRIPTION         top

       xfsdump backs up files and their attributes in a filesystem.  The
       files are dumped to storage media, a regular file, or standard
       output.  Options allow the operator to have all files dumped,
       just files that have changed since a previous dump, or just files
       contained in a list of pathnames.

       The xfsrestore(8) utility re-populates a filesystem with the
       contents of the dump.

       Each invocation of xfsdump dumps just one filesystem.  That
       invocation is termed a dump session.  The dump session splits the
       filesystem into one or more dump streams, one per destination.
       The split is done in filesystem inode number (ino) order, at
       boundaries selected to equalize the size of each stream.
       Furthermore, the breakpoints between streams may be in the middle
       of very large files (at extent boundaries) if necessary to
       achieve reasonable stream size equalization.  Each dump stream
       can span several media objects, and a single media object can
       contain several dump streams.  The typical media object is a tape
       cartridge.  The media object records the dump stream as one or
       more media files.  A media file is a self-contained partial dump,
       intended to minimize the impact of media dropouts on the entire
       dump stream at the expense of increasing the time required to
       complete the dump. By default only one media file is written
       unless a media file size is specified using the -d option. Other
       techniques, such as making a second copy of the dump image,
       provide more protection against media failures than multiple
       media files will.

       xfsdump maintains an online dump inventory in
       /var/lib/xfsdump/inventory.  The -I option displays the inventory
       contents hierarchically.  The levels of the hierarchy are:
       filesystem, dump session, stream, and media file.

       The options to xfsdump are:

       -a   Specifies that files for which the Data Migration Facility
            (DMF) has complete offline copies (dual-state files) be
            treated as if they were offline (OFL).  This means that the
            file data will not be dumped by xfsdump, resulting in a
            smaller dump file.  If the file is later restored the file
            data is still accessible through DMF.  If both '-a option'
            and '-z option' are specified, the '-a option' takes
            precedence (see '-z option' below).

       -b blocksize
            Specifies the blocksize, in bytes, to be used for the dump.
            The same blocksize must be specified to restore the tape.
            If the -m option is not used, then -b does not need to be
            specified. Instead, a default blocksize of 1Mb will be used.

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

       -d filesize
            Specifies the size, in megabytes, of dump media files.  If
            not specified, xfsdump will dump data to tape using a single
            media file per media object.  The specified media file size
            may need to be adjusted if, for example, xfsdump cannot fit
            a media file onto a single tape.

       -e   Allow files to be excluded from the dump.  This will cause
            xfsdump to skip files which have the "no dump" file
            attribute set. See the "Excluding individual files" section
            below for details on setting this file attribute.

       -f dest [ -f dest ... ]
            Specifies a dump destination.  A dump destination 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 output option (a lone - preceding
            the source filesystem specification) is specified.

       -l level
            Specifies a dump level of 0 to 9.  The dump level determines
            the base dump to which this dump is relative.  The base dump
            is the most recent dump at a lesser level.  A level 0 dump
            is absolute - all files are dumped.  A dump level where 1 <=
            level <= 9 is referred to as an incremental dump.  Only
            files that have been changed since the base dump are dumped.
            Subtree dumps (see the -s option below) cannot be used as
            the base for incremental dumps.

       -m   Use the minimal tape protocol for non-scsi tape destinations
            or remote tape destinations which are not scsi Linux tape
            drives nor IRIX tape drives.  This option cannot be used
            without specifying a blocksize to be used (see -b option
            above).

       -o   Overwrite the tape. With this option, xfsdump does not read
            the tape first to check the contents. This option may be
            used if xfsdump is unable to determine the block size of a
            tape .

       -p interval
            Causes progress reports to be printed at the specified
            interval.  interval is given in seconds.  The progress
            report indicates how many files have been dumped, the total
            number of files to dump, the percentage of data dumped, and
            the elapsed time.

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

       -s pathname [ -s pathname ... ]
            Restricts the dump to files contained in the specified
            pathnames (subtrees).  A pathname must be relative to the
            mount point of the filesystem.  For example, if a filesystem
            is mounted at /d2, the pathname argument for the directory
            /d2/users is ``users''.  A pathname can be a file or a
            directory; if it is a directory, the entire hierarchy of
            files and subdirectories rooted at that directory is dumped.
            Subtree dumps cannot be used as the base for incremental
            dumps (see the -l option above).

       -t file
            Sets the dump time to the modification time of file rather
            than using the current time.  xfsdump uses the dump time to
            determine what files need to be backed up during an
            incremental dump. This option should be used when dumping
            snapshots so that the dump time matches the time the
            snapshot was taken. Otherwise files modified after a
            snapshot is taken may be skipped in the next incremental
            dump.

       -v verbosity
       -v subsys=verbosity[,subsys=verbosity,...]
            Specifies the level of detail used for messages displayed
            during the course of the dump. 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 dump 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, inomap and
            excluded_files.

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

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

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

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

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

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

            To list files that will be excluded from the dump:

                 # xfsdump -e -v excluded_files=debug -f /dev/tape /

       -z size
            Specifies the maximum size, in kilobytes, of files to be
            included in the dump.  Files over this size, will be
            excluded from the dump, except for DMF dual-state files when
            '-a option' is specified (see '-a option' above).  When
            specified, '-a option' takes precedence over '-z option'.
            The size is an estimate based on the number of disk blocks
            actually used by the file, and so does not include holes.
            In other words, size refers to the amount of space the file
            would take in the resulting dump.  On an interactive
            restore, the skipped file is visible with xfsrestore's 'ls'
            and while you can use the 'add' and 'extract' commands,
            nothing will be restored.

       -A   Do not dump extended file attributes.  When dumping 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 dumps containing extended file
            attributes cannot be restored with older versions of
            xfsrestore(8).

       -B session_id
            Specifies the ID of the dump session upon which this dump
            session is to be based.  If this option is specified, the -l
            (level) and -R (resume) options are not allowed.  Instead,
            xfsdump determines if the current dump session should be
            incremental and/or resumed, by looking at the base session's
            level and interrupted attributes.  If the base session was
            interrupted, the current dump session is a resumption of
            that base at the same level.  Otherwise, the current dump
            session is an incremental dump with a level one greater than
            that of the base session.  This option allows incremental
            and resumed dumps to be based on any previous dump, rather
            than just the most recent.

       -D   Controls which directories are backed up during an
            incremental dump. By default unchanged directories are
            dumped if files or directories beneath them have changed.
            This results in a self-contained dump -- if a base dump is
            lost, or you know the file(s) you wish to restore is in an
            incremental dump, you can restore just that dump without
            loading the base dump(s) first. However, this method
            requires a potentially expensive traversal through the
            filesystem.

            When -D is specified, unchanged directories are not dumped.
            This results in a faster dump, but files will end up in the
            xfsrestore(8) orphanage directory unless the base dump(s) is
            loaded first.

       -E   Pre-erase media.  If this option is specified, media is
            erased prior to use.  The operator is prompted for
            confirmation, unless the -F option is also specified.

       -F   Don't prompt the operator.  When xfsdump encounters a media
            object containing non-xfsdump data, xfsdump normally asks
            the operator for permission to overwrite.  With this option
            the overwrite is performed, no questions asked.  When
            xfsdump encounters end-of-media during a dump, xfsdump
            normally asks the operator if another media object will be
            provided.  With this option the dump is instead interrupted.

       -I   Displays the xfsdump inventory (no dump is performed).
            xfsdump records each dump session in an online inventory in
            /var/lib/xfsdump/inventory.  xfsdump uses this inventory to
            determine the base for incremental dumps.  It is also useful
            for manually identifying a dump session to be restored.
            Suboptions to filter the inventory display are described
            later.

       -J   Inhibits the normal update of the inventory.  This is useful
            when the media being dumped to will be discarded or
            overwritten.

       -K   Generate a format 2 dump instead of the current format. This
            is useful if the dump will be restored on a system with an
            older xfsrestore which does not understand the current dump
            format. Use of this option is otherwise not recommended.

       -L session_label
            Specifies a label for the dump session.  It can be any
            arbitrary string up to 255 characters long.

       -M label [ -M label ... ]
            Specifies a label for the first media object (for example,
            tape cartridge) written on the corresponding destination
            during the session.  It can be any arbitrary string up to
            255 characters long.  Multiple media object labels can be
            specified, one for each destination.

       -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 source filesystem cannot be specified in
            options_file.

       -R   Resumes a previously interrupted dump session.  If the most
            recent dump at this dump's level (-l option) was
            interrupted, this dump contains only files not in the
            interrupted dump and consistent with the incremental level.
            However, files contained in the interrupted dump that have
            been subsequently modified are re-dumped.

       -T   Inhibits interactive dialogue timeouts.  When the -F option
            is not specified, xfsdump prompts the operator for labels
            and media changes.  Each dialogue normally times out if no
            response is supplied.  This option prevents the timeout.

       -Y length
            Specify I/O buffer ring length.  xfsdump uses a ring of
            output buffers to achieve maximum throughput when dumping to
            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 dump stream to be sent to the standard
            output, where it can be piped to another utility such as
            xfsrestore(8) or redirected to a file.  This option cannot
            be used with the -f option.  The - must follow all other
            options and precede the filesystem specification.

       The filesystem, filesystem, can be specified either as a mount
       point or as a special device file (for example,
       /dev/dsk/dks0d1s0).  The filesystem must be mounted to be dumped.

NOTES         top

   Dump Interruption
       A dump can be interrupted at any time and later resumed.  To
       interrupt, type control-C (or the current terminal interrupt
       character).  The operator is prompted to select one of several
       operations, including dump interruption.  After the operator
       selects dump interruption, the dump continues until a convenient
       break point is encountered (typically the end of the current
       file).  Very large files are broken into smaller subfiles, so the
       wait for the end of the current file is brief.

   Dump Resumption
       A previously interrupted dump can be resumed by specifying the -R
       option.  If the most recent dump at the specified level was
       interrupted, the new dump does not include files already dumped,
       unless they have changed since the interrupted dump.

   Media Management
       A single media object can contain many dump streams.  Conversely,
       a single dump stream can span multiple media objects.  If a dump
       stream is sent to a media object already containing one or more
       dumps, xfsdump appends the new dump stream after the last dump
       stream.  Media files are never overwritten.  If end-of-media is
       encountered during the course of a dump, the operator is prompted
       to insert a new media object into the drive.  The dump stream
       continuation is appended after the last media file on the new
       media object.

   Inventory
       Each dump session updates an inventory database in
       /var/lib/xfsdump/inventory.  xfsdump uses the inventory to
       determine the base of incremental and resumed dumps.

       This database can be displayed by invoking xfsdump 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.  Its contents may be merged back into
       the online inventory database at a later time using
       xfsrestore(1M).

       The inventory files stored in /var/lib/xfsdump are not included
       in the dump, even if that directory is contained within the
       filesystem being dumped.  Including the inventory in the dump may
       lead to loss or corruption of data, should an older version be
       restored overwriting the current version.  To backup the xfsdump
       inventory, the contents of /var/lib/xfsdump should be copied to
       another location which may then be safely dumped.  Upon
       restoration, those files may be copied back into
       /var/lib/xfsdump, overwriting whatever files may be there, or
       xfsinvutil(1M) may be used to selectively merge parts of the
       restored inventory back into the current inventory.  Prior to
       version 1.1.8, xfsdump would include the /var/lib/xfsdump
       directory in the dump.  Care should be taken not to overwrite the
       /var/lib/xfsdump directory when restoring an old dump, by either
       restoring the filesystem to another location or by copying the
       current contents of /var/lib/xfsdump to a safe place prior to
       running xfsrestore(1M).

   Labels
       The operator can specify a label to identify the dump session and
       a label to identify a media object.  The session label is placed
       in every media file produced in the course of the dump, and is
       recorded in the inventory.

       The media label is used to identify media objects, and is
       independent of the session label.  Each media file on the media
       object contains a copy of the media label.  An error is returned
       if the operator specifies a media label that does not match the
       media label on a media object containing valid media files.
       Media labels are recorded in the inventory.

   UUIDs
       UUIDs (Universally Unique Identifiers) are used in three places:
       to identify the filesystem being dumped (using the filesystem
       UUID, see xfs(5) for more details), to identify the dump session,
       and to identify each media object.  The inventory display (-I)
       includes all of these.

   Dump Level Usage
       The dump level mechanism provides a structured form of
       incremental dumps.  A dump of level level includes only files
       that have changed since the most recent dump at a level less than
       level.  For example, the operator can establish a dump schedule
       that involves a full dump every Friday and a daily incremental
       dump containing only files that have changed since the previous
       dump.  In this case Friday's dump would be at level 0, Saturday's
       at level 1, Sunday's at level 2, and so on, up to the Thursday
       dump at level 6.

       The above schedule results in a very tedious restore procedure to
       fully reconstruct the Thursday version of the filesystem;
       xfsrestore would need to be fed all 7 dumps in sequence.  A
       compromise schedule is to use level 1 on Saturday, Monday, and
       Wednesday, and level 2 on Sunday, Tuesday, and Thursday.  The
       Monday and Wednesday dumps would take longer, but the worst case
       restore requires the accumulation of just three dumps, one each
       at level 0, level 1, and level 2.

   Quotas
       If the filesystem being dumped contains user quotas, xfsdump will
       use xfs_quota(8) to store the quotas in a file called
       xfsdump_quotas in the root of the filesystem to be dumped. This
       file will then be included in the dump.  Upon restoration,
       xfs_quota(8) can be used to reactivate the quotas for the
       filesystem.  Note, however, that the xfsdump_quotas file will
       probably require modification to change the filesystem or UIDs if
       the filesystem has been restored to a different partition or
       system. Group and project quotas will be handled in a similar
       fashion and saved in files called xfsdump_quotas_group and
       xfsdump_quotas_proj , respectively.

   Excluding individual files
       It may be desirable to exclude particular files or directories
       from the dump.  The -s option can be used to limit the dump to a
       specified directory, and the -z option can be used to exclude
       files over a particular size.  Additionally, when xfsdump is run
       with the -e option, files that are tagged with the "no dump" file
       attribute will not be included in the dump.  The chattr(1)
       command can be used to set this attribute on individual files or
       entire subtrees.

       To tag an individual file for exclusion from the dump:

            $ chattr +d file

       To tag all files in a subtree for exclusion from the dump:

            $ chattr -R +d directory

       Note that any new files or directories created in a directory
       which has the "no dump" attribute set will automatically inherit
       this attribute.  Also note that xfsdump does not check
       directories for the "no dump" attribute.

       Care should be taken to note which files have been tagged.  Under
       normal operation, xfsdump will only report the number of files it
       will skip.  The -v excluded_files=debug option, however, will
       cause xfsdump to list the inode numbers of the individual files
       affected.

EXAMPLES         top

       To perform a level 0, single stream dump of the root filesystem
       to a locally mounted tape drive, prompting for session and media
       labels when required:

            # xfsdump -f /dev/tape /

       To specify session and media labels explicitly:

            # xfsdump -L session_1 -M tape_0 -f /dev/tape /

       To perform a dump to a remote tape using the minimal rmt protocol
       and a set blocksize of 64k:

            # xfsdump -m -b 65536 -f otherhost:/dev/tape /

       To perform a level 0, multi-stream dump to two locally mounted
       tape drives:

            # xfsdump -L session_2 -f /dev/rmt/tps4d6v -M tape_1 \
                      -f /dev/rmt/tps5d6v -M tape_2 /

       To perform a level 1 dump relative to the last level 0 dump
       recorded in the inventory:

            # xfsdump -l 1 -f /dev/tape /

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

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

FILES         top

       /var/lib/xfsdump/inventory
              dump inventory database

SEE ALSO         top

       attr(1), rmt(8), xfsrestore(8), xfsinvutil(8), xfs_quota(8),
       attr_get(2).

DIAGNOSTICS         top

       The exit code is 0 on normal completion, non-zero if an error
       occurs or the dump is terminated by the operator.

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

            xfsdump: Dump Status: code

       Where code takes one of the following values: SUCCESS (normal
       completion), INTERRUPT (interrupted), QUIT (media no longer
       usable), INCOMPLETE (dump 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 xfsdump.  However, it may be necessary to
       refine or expand the set of exit codes, or their interpretation
       at some point in the future.

       The message ``xfsdump: WARNING: unable to open directory: ino N:
       Invalid argument'' can occur with filesystems which are actively
       being modified while xfsdump is running.  This can happen to
       either directory or regular file inodes - affected files will not
       end up in the dump, files below affected directories will be
       placed in the orphanage directory by xfsrestore.

BUGS         top

       xfsdump does not dump unmounted filesystems.

       The dump frequency field of /etc/fstab is not supported.

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

       xfsdump requires root privilege (except for inventory display).

       xfsdump can only dump XFS filesystems.

       The media format used by xfsdump can only be understood by
       xfsrestore.

       xfsdump does not know how to manage CD-ROM or other removable
       disk drives.

       xfsdump can become confused when doing incremental or resumed
       dumps if on the same machine you dump two XFS filesystems and
       both filesystems have the same filesystem identifier (UUID).
       Since xfsdump uses the filesystem identifier to identify
       filesystems, xfsdump maintains one combined set of dump
       inventories for both filesystems instead of two sets of dump
       inventories.  This scenario can happen only if dd or some other
       block-by-block copy program was used to make a copy of an XFS
       filesystem.  See xfs_copy(8) and xfs(5) for more details.

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
       linux-xfs@vger.kernel.org.  This page was obtained from the
       project's upstream Git repository
       ⟨https://git.kernel.org/pub/scm/fs/xfs/xfsprogs-dev.git⟩ on
       2023-12-22.  (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 man-pages@man7.org

                                                              xfsdump(8)

Pages that refer to this page: attr(1)chacl(1)xfs(5)xfs_copy(8)xfsinvutil(8)xfsrestore(8)