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, see 
       ⟨http://oss.sgi.com/bugzilla/buglist.cgi?product=XFS⟩.  This page was
       obtained from the project's upstream Git repository 
       ⟨git://git.kernel.org/pub/scm/fs/xfs/xfsprogs-dev.git⟩ on 2017-04-25.
       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)