| xfsdump(8) | System Manager's Manual | xfsdump(8) |
xfsdump - XFS filesystem incremental dump utility
xfsdump -h xfsdump [ options ] -f dest [ -f dest ... ] filesystem xfsdump [ options ] - filesystem xfsdump -I [ subopt=value ... ]
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:
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 /
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.
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 -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.
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 /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.
The display may be restricted to media files contained in a specific media object.
Similarly, the display can be restricted to a specific filesystem.
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).
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 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.
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.
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.
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
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
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.
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.