Section: Maintenance Commands (8)
Return to Main Contents
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
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.
utility re-populates a filesystem with the contents of the dump.
Each invocation of
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
option. Other techniques, such as making a second copy of the dump
image, provide more protection against media failures than multiple
media files will.
maintains an online dump inventory in /var/lib/xfsdump/inventory.
option displays the inventory contents hierarchically.
The levels of the hierarchy are:
The options to
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.
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
preceding the source filesystem specification)
- -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.
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
Overwrite the tape. With this option,
does not read the tape first to check the contents. This option may
be used if
is unable to determine the block size of a tape .
- -p interval
Causes progress reports to be printed at the specified 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,
the elapsed time.
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
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
Subtree dumps cannot be used as the base for incremental dumps
- -t file
Sets the dump time to the modification time of file rather than
using the current time.
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
- -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
# 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
# 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
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
are not allowed.
determines if the current dump session should be incremental
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.
is specified, unchanged directories are not dumped.
This results in a faster dump, but files will end up in the
directory unless the base dump(s) is loaded first.
If this option is specified, media is erased prior to use.
The operator is prompted for confirmation,
option is also specified.
Don't prompt the operator.
encounters a media object containing non-xfsdump data,
normally asks the operator for permission to overwrite.
With this option the overwrite is performed, no questions asked.
encounters end-of-media during a dump,
normally asks the operator if another media object will be provided.
With this option the dump is instead interrupted.
Displays the xfsdump inventory
(no dump is performed).
records each dump session in an online inventory
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
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
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)
this dump contains only files not in the interrupted dump
and consistent with the incremental level.
files contained in the interrupted dump that have been subsequently
modified are re-dumped.
Inhibits interactive dialogue timeouts.
option is not specified,
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.
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.
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
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.
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
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.
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,
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 /var/lib/xfsdump/inventory
uses the inventory to determine the base of incremental
and resumed dumps.
This database can be displayed by invoking
The display uses tabbed indentation to present the inventory
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
is 1, 2, or 3) limits the hierarchical depth of the display. When
is 1, only the filesystem information from the inventory is displayed. When
is 2, only filesystem and session information are displayed. When
is 3, only filesystem, session and stream information are displayed.
- -I level=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
- -I mobjid=value
is a media ID) specifies the media object by its media ID.
- -I mobjlabel=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
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.
-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 using
The inventory files stored in
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
inventory, the contents of
should be copied to another location which may then be safely dumped.
Upon restoration, those files may be copied back into
overwriting whatever files may be there, or
may be used to selectively merge parts of the restored inventory back
into the current inventory. Prior to version 1.1.8,
would include the
directory in the dump. Care should be taken not to overwrite the
directory when restoring an old dump, by either restoring the
filesystem to another location or by copying the current contents of
to a safe place prior to running
The operator can specify a label to identify the dump
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
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,
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
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 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,
to store the quotas in a file called
in the root of the filesystem to be dumped. This file will then be
included in the dump. Upon restoration,
can be used to reactivate the quotas for the filesystem.
Note, however, that the
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
Excluding individual files
It may be desirable to exclude particular files or directories from
the dump. The
option can be used to limit the dump to a specified directory, and the
option can be used to exclude files over a particular size. Additionally,
is run with the
option, files that are tagged with the "no dump" file attribute
will not be included in the dump. The
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
does not check directories for the "no dump" attribute.
Care should be taken to note which files have been tagged.
Under normal operation,
will only report the number of files it will skip. The
option, however, will cause
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 xfsrestore(8)):
# xfsdump -J - / | xfsrestore -J - /new
dump inventory database
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),
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.
``xfsdump: WARNING: unable to open directory: ino N: Invalid argument''
can occur with filesystems which are actively being modified while
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
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
xfsdump does not know how to manage CD-ROM or other removable
xfsdump can become confused when doing incremental or
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
xfsdump maintains one combined set of dump inventories
for both filesystems instead of two sets of dump inventories.
This scenario can happen only if
or some other block-by-block copy program was used to make
a copy of an XFS filesystem.
for more details.