xfsdump - XFS filesystem incremental dump utility
xfsdump [ options ] -f dest [ -f dest ... ] filesystem
xfsdump [ options ] - filesystem
xfsdump -I [ subopt=value ... ]
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.
(8) utility re-populates a filesystem with the contents of
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
option. Other techniques, such as making a second copy of the dump
image, provide more protection against media failures than multiple media
maintains an online dump inventory in
. 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
- 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'
- -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.
- 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.
- 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).
- 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.
- Destination tape drive is a QIC tape. QIC tapes only use a
512 byte blocksize, for which xfsdump must make special
- -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
- -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
- 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
# 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
# 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.
- 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.
- 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
- 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.
- 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
- 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.
- Inhibits the normal update of the inventory. This is useful
when the media being dumped to will be discarded or overwritten.
- 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
- -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.
- 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.
- 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
filesystem must be mounted to be dumped.
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.
A previously interrupted dump can be resumed by specifying the -R
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
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.
Each dump session updates an inventory database in
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
- -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
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
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
inventory, the contents of /var/lib/xfsdump
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
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
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 (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.
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
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.
If the filesystem being dumped contains user quotas, xfsdump
(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
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
and xfsdump_quotas_proj ,
It may be desirable to exclude particular files or directories from the dump.
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
Care should be taken to note which files have been tagged. Under normal
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.
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
# xfsdump -l 1 -f /dev/tape /
To copy the contents of a filesystem to another directory (see
# xfsdump -J - / | xfsrestore -J - /new
- dump inventory database
attr(1), rmt(8), xfsrestore(8), xfsinvutil(8), xfs_quota(8), attr_get(2).
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
takes one of the following values: SUCCESS
(media no longer
(dump incomplete), FAULT
(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
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
does not dump unmounted filesystems.
The dump frequency field of /etc/fstab
is not supported.
uses the alert program only when a media change is required.
requires root privilege (except for inventory display).
can only dump XFS filesystems.
The media format used by xfsdump
can only be understood by
does not know how to manage CD-ROM or other removable disk
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
(8) and xfs
(5) for more details.