xfsdump(8)

💾 xfsdump — the XFS filesystem incremental dump utility (from the System Manager's Manual, section 8) ✨

okay bestie, sit down, hydrate, because this is the one that saves your whole entire filesystem when everything goes sideways 🫶

---

🌸 NAME 🌸

xfsdump — XFS filesystem incremental dump utility 💅

---

✨ SYNOPSIS ✨

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

---

🦋 DESCRIPTION 🦋

okay so xfsdump backs up files and their attributes in a filesystem. like, the whole vibe, not just the bytes. the files get dumped to storage media, a regular file, or standard output — dealer's choice 💖

the options let the operator decide: all files dumped, just the files that changed since a previous dump, or just files that live inside a list of pathnames. very choose-your-own-adventure.

and then xfsrestore(8) is the reverse queen — she re-populates a filesystem with the contents of the dump. they're a package deal, fr fr.

every single invocation of xfsdump dumps just one filesystem. one invocation = one dump session. iconic. a dump session splits the filesystem into one or more dump streams, one per destination. the split happens in filesystem inode number (ino) order, at boundaries picked so that each stream ends up roughly the same size. and listen — the breakpoints between streams can land in the middle of very large files (at extent boundaries) if that's what it takes to equalize the stream sizes. it's giving "we'll cut wherever we need to."

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, and the whole point of it is to minimize the impact of media dropouts on the entire dump stream — at the cost 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. and ngl, other techniques (like making a second copy of the dump image) give you more protection against media failures than multiple media files ever will. just saying 👀

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

---

💅 OPTIONS 💅

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 the file data will not be dumped by xfsdump, which results 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. 🚨 bestie, pay 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. periodt.
• -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). no blocksize, no service 😤
• -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. 📊 we love a progress bar moment
• -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. ⏰ lowkey important, don't skip this one
• -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. 💀 the file's there but it's giving ghost
• -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). ⚠️ careful bestie
• -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. 🏚️ orphanage arc, not the vibe you want

• -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 — bestie, this one says don't prompt the operator, like, at all. Normally when xfsdump bumps into a media object that's got non-xfsdump data on it, it's gonna politely ask you for permission to overwrite. With -F? It just does it, no questions asked 💅. Same energy for end-of-media: normally xfsdump asks the operator if another media object is coming. With this flag, nope — the dump is instead interrupted. Not a vibe for the faint of heart.
• -I — shows you the xfsdump inventory and performs no dump at all. Because here's the tea: xfsdump records every single dump session in an online inventory over in /var/lib/xfsdump/inventory, and it uses that inventory to figure out the base for incremental dumps. It's also lowkey perfect for manually identifying a dump session you wanna restore. Suboptions to filter the inventory display? Those show up later, iykyk. ✨
• -J — inhibits the normal update of the inventory. Super handy when the media you're dumping to is gonna get discarded or overwritten anyway. No point updating the receipts for a tape that's headed to the bin 🗑️.
• -K — generates a format 2 dump instead of the current format. This is the move if your dump is gonna be restored on a system running an older xfsrestore that doesn't understand the current dump format. > Heads up bestie: use of this option is otherwise not recommended. It's giving "only if you absolutely have to" 🫶
• -L session_label — sets a label for the dump session. It can be any arbitrary string up to 255 characters long. Name it something cute, go wild 🎀
• -M label [ -M label ... ] — labels the first media object written on the corresponding destination during the session (think: a tape cartridge, bestie). Any arbitrary string up to 255 characters long. And you can specify multiple media object labels — one for each destination 👑
• -O options_file — inserts the options sitting inside options_file right at the beginning of the command line. The options are specified just as they would appear if you typed them into the command line. Bonus: newline characters (\n) can be used as whitespace 🌸. Where do they land? Before all the options actually given on the command line, just after the command name. Rules though: only one -O option can be used, recursive use is ignored, and the source filesystem cannot be specified in options_file.
• -R — resumes a previously interrupted dump session. So if the most recent dump at this dump's level (that's the -l option) got interrupted, this dump contains only the files that weren't in the interrupted dump and are consistent with the incremental level. But — and this is important — files that were in the interrupted dump and have since been modified get re-dumped. Consistency, periodt 💖
• -T — inhibits interactive dialogue timeouts. Here's the setup: when -F is not specified, xfsdump prompts the operator for labels and media changes, and each dialogue normally times out if nobody responds. This option stops the timeout from happening at all. Take your sweet time, no pressure 😌
• -Y length — specify the I/O buffer ring length. xfsdump uses a ring of output buffers to achieve maximum throughput when dumping to tape drives, and the default ring length is 3. > But fr fr: this is not currently enabled on Linux yet, making this option benign. So it's basically decorative on your machine 💀
• - — a lone - causes the dump stream to be sent to standard output, where you can pipe it to another utility like xfsrestore(8) or redirect it to a file. It's giving main character energy for pipelines 🌈. But rules are rules: this option cannot be used with the -f option, and the - must follow all other options and precede the filesystem specification. Order matters, bestie ⭐

---

The filesystem — filesystem — can be specified either as a mount point or as a special device file (for example, /dev/dsk/dks0d1s0). And ngl, the filesystem must be mounted to be dumped. No mount, no dump, no exceptions 💜

✨ NOTES ✨

🛑 Dump Interruption

okay so bestie, you can literally interrupt a dump whenever and pick it back up later 💅. Just hit control-C (or whatever your terminal's current interrupt character is). Then you get prompted to pick from a bunch of operations, and one of them is interrupting the dump. Once you choose that, the dump keeps going until it hits a convenient break point — usually the end of the current file. And don't stress about waiting forever, because very large files get broken into smaller subfiles, so that wait is short. 🫶

▶️ Dump Resumption

Got a dump that got interrupted? You can resume it by passing the -R option. Here's the tea: if the most recent dump at the level you specified was interrupted, the new dump skips files that were already dumped — unless they've changed since that interrupted dump. 👑

📼 Media Management

One media object can hold a bunch of dump streams. And plot twist, one dump stream can span multiple media objects. If you send a dump stream to a media object that already has one or more dumps on it, xfsdump appends the new stream after the last one. Media files are never overwritten, periodt. If you hit end-of-media mid-dump, the operator gets prompted to stick a new media object in the drive, and the stream continuation gets appended after the last media file on that new media object. ✨

🗂️ Inventory

Every dump session updates an inventory database living in /var/lib/xfsdump/inventory. xfsdump uses this inventory to figure out the base of incremental and resumed dumps. Fr fr, it's the backbone.

You can display this database by running xfsdump with the -I option. The display uses tabbed indentation to show the inventory hierarchically:

1. First level = filesystem
2. Second level = session
3. Third level = media stream (currently only one stream is supported)
4. Fourth level = the media files sequentially composing the stream

And there are these suboptions to filter what you see:

• -I depth=n — where n is 1, 2, or 3, limits how deep the hierarchy goes. n is 1: only filesystem info shows. n is 2: only filesystem and session info. n is 3: only filesystem, session and stream info.
• -I level=n — where n is the dump level, limits the display to dumps at that particular dump level.
• -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.
• -I mnt=mount_point — that is, [hostname:]pathname, identifies the filesystem by mountpoint. The hostname is optional but lowkey 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. Same as the mnt filter, the hostname is optional.

You can stack more than one of these suboptions at the same time, separated by commas, to narrow the display to just the dumps you care about. But heads up: at most four suboptions at once — one to constrain the display hierarchy depth, one for the dump level, one for the media object, and one for the filesystem. No more than that. 💀

For example, -I depth=1,mobjlabel="tape 1",mnt=host1:/test_mnt would show only the filesystem info (depth=1) for those filesystems mounted on host1:/test_mnt at the time of the dump, and only the ones dumped to the media object labeled "tape 1".

Dump records can be removed (pruned) from the inventory using the xfsinvutil program. 🧹

Also, an extra media file gets placed at the end of each dump stream. That media file holds the inventory information for the current dump session, and you can merge its contents back into the online inventory database later using xfsrestore(1M).

The inventory files stored in /var/lib/xfsdump are not included in the dump, even if that directory is inside the filesystem being dumped. Why? Because including the inventory in the dump could lead to loss or corruption of data if an older version gets restored and overwrites the current version. 😭

To back up the xfsdump inventory, copy the contents of /var/lib/xfsdump to another location, which you can then safely dump. On restoration, copy those files back into /var/lib/xfsdump, overwriting whatever's there — or use xfsinvutil(1M) to selectively merge parts of the restored inventory back into the current one.

📢 History lesson: prior to version 1.1.8, xfsdump would include the /var/lib/xfsdump directory in the dump. So be careful not to overwrite /var/lib/xfsdump when restoring an old dump — either restore the filesystem to another location, or copy the current contents of /var/lib/xfsdump somewhere safe before running xfsrestore(1M).

🏷️ Labels

The operator can specify a label to identify the dump session, plus a label to identify a media object. The session label goes into every media file produced during the dump, and it's recorded in the inventory.

The media label identifies media objects, and it's totally independent of the session label. Each media file on the media object carries a copy of the media label. If you specify a media label that doesn't match the media label on a media object containing valid media files, you get an error. 🚨 Media labels are also recorded in the inventory.

🆔 UUIDs

UUIDs (Universally Unique Identifiers) get used in three places: to identify the filesystem being dumped (via the filesystem UUID — peep xfs(5) for more deets), to identify the dump session, and to identify each media object. The inventory display (-I) shows all of these. 🌈

📊 Dump Level Usage

The dump level mechanism gives you 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, you could set up a schedule with a full dump every Friday and a daily incremental containing only files changed since the previous dump. Friday's dump = level 0, Saturday's = level 1, Sunday's = level 2, and so on up to the Thursday dump at level 6.

Now, that schedule makes for a very tedious restore if you want to fully reconstruct the Thursday version of the filesystem — xfsrestore would need to be fed all 7 dumps in sequence. 😮‍💨 A compromise schedule: use level 1 on Saturday, Monday, and Wednesday, and level 2 on Sunday, Tuesday, and Thursday. The Monday and Wednesday dumps take longer, but worst case restore only needs three dumps accumulated — one each at level 0, level 1, and level 2. Slay. 👑

💰 Quotas

If the filesystem you're dumping has user quotas, xfsdump will use xfs_quota(8) to store the quotas in a file called xfsdump_quotas in the root of the filesystem being dumped. That file then gets included in the dump. On restoration, xfs_quota (8) can reactivate the quotas for the filesystem. But note: the xfsdump_quotas file will probably need modification to change the filesystem or UIDs if the filesystem was restored to a different partition or system. Group and project quotas get handled similarly, saved in files called xfsdump_quotas_group and xfsdump_quotas_proj , respectively.

🚫 Excluding individual files

Sometimes you wanna exclude particular files or directories from the dump, and that's valid. The -s option limits the dump to a specified directory, and the -z option excludes files over a particular size. Also, when xfsdump runs with the -e option, files tagged with the "no dump" file attribute won't be included. The chattr(1) command sets that 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

Heads up: any new files or directories created in a directory that has the "no dump" attribute set will automatically inherit that attribute. And also note that xfsdump does not check directories for the "no dump" attribute. 🙈

Care should be taken to note which files you've tagged. Under normal operation, xfsdump will only report the number of files it will skip. But the -v excluded_files=debug option makes xfsdump list the inode numbers of the individual files affected. 🔍

---

🌸 EXAMPLES 🌸

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 🎀

• /var/lib/xfsdump/inventory — dump inventory database

---

💖 SEE ALSO 💖

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

💅 DIAGNOSTICS 💅

Okay bestie, let's talk exit codes, because they're literally the vibe check for whether your dump ate or flopped. 💖

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

For all verbosity levels greater than 0 (that's the silent one), the final line of the output shows the exit status of the dump. It's giving:

xfsdump: Dump Status: code

Where code takes one of these iconic values:

• SUCCESS — normal completion, we love a clean finish ✨
• INTERRUPT — interrupted, rude tbh 😭
• QUIT — media no longer usable, the tape said bye 💀
• INCOMPLETE — dump incomplete, not the full slay 🙈
• FAULT — software error, big yikes 🫠
• ERROR — resource error, the vibes are off 🔥

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. So like, don't @ me if the code list grows. 🌈

Also, heads up: 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, and files below affected directories will be placed in the orphanage directory by xfsrestore. Not the cutest, but now you know. 💜

😭 BUGS 😭

Okay so not everything is slay, here's the tea:

• xfsdump does not dump unmounted filesystems. Unmounted? Not happening. 🫶
• The dump frequency field of /etc/fstab is not supported. It's giving unsupported, sorry. 💅
• xfsdump uses the alert program only when a media change is required. Just so you know. ⭐
• xfsdump requires root privilege (except for inventory display). So like, root or bust. 👑
• xfsdump can only dump XFS filesystems. No XFS, no dump, no cap. 🦋
• The media format used by xfsdump can only be understood by xfsrestore. They're exclusive, iykyk. 💖
• xfsdump does not know how to manage CD-ROM or other removable disk drives. It's not that girl for those. 🎀
• 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. So like, don't clone your UUIDs and then act surprised. 💀

---

And that's the xfsdump(8) page, bestie! Source/version: xfsdump(8). Date: the one in the footer, but the vibe is eternal. Stay slay, stay backed up. 💖✨👑