xfsrestore(8)

💖 xfsrestore 💖

okay bestie, welcome to xfsrestore(8) from the System Manager's Manual — yes the whole glow-up, section 8 and all. this is the page that tells you how to put your filesystem back, and honestly it's giving time-travel but for files. let's get into it 🦋✨

---

✨ NAME ✨

xfsrestore — XFS filesystem incremental restore utility

like, it un-dumps your dumps. periodt.

---

🌸 SYNOPSIS 🌸

xfsrestore -h
xfsrestore [ options ] -f source [ -f source ... ] dest
xfsrestore [ options ] - dest
xfsrestore -I [ subopt=value ... ]

---

👑 DESCRIPTION 👑

xfsrestore restores filesystems from dumps produced by xfsdump(8). there are two modes of operation, bestie: simple and cumulative.

the default is simple mode. xfsrestore populates the destination directory you named, dest, with all the files that were chillin' inside the dump media.

the -r option is what unlocks cumulative mode. here you invoke xfsrestore over and over, applying a chronologically ordered sequence of delta dumps on top of a base (level 0) dump. the result reproduces exactly what the filesystem looked like at the moment each dump was produced. and yeah, that can mean adding, deleting, renaming, linking, and unlinking files and directories — full makeover energy 💅

so what even is a delta dump? it's defined as either:

• an incremental dump (xfsdump -l option with level > 0), or
• a resumed dump (xfsdump -R option).

the deltas must be applied in the order they were produced. no skipping around. each delta you apply must have been produced with the previously applied delta as its base — it's a chain, bestie, don't break it 🔗

xfsrestore keeps state information in the xfsrestorehousekeepingdir, so it can tell subsequent invocations what's up when you're in cumulative mode, or in case a restore gets interrupted mid-slay. to make sure that state info can actually be processed:

• you have to use a compatible version of xfsrestore for each subsequent invocation, and
• each invocation must run on a system with the same endianness and page size.

lowkey important: mismatch either of those and the state info is not gonna vibe with you. no cap.

---

🎀 OPTIONS 🎀

the options to xfsrestore are:

• -a housekeeping — every single invocation of xfsrestore creates a directory called xfsrestorehousekeepingdir, normally right under the dest directory. this option lets the operator pick an alternate directory, housekeeping, and xfsrestore will create the xfsrestorehousekeepingdir directory inside that instead. when you're doing a cumulative restore (-r option) or resuming a restore (-R option), every successive invocation must specify the same alternate directory. consistency is the vibe. 🔁
• -b blocksize — specifies the blocksize, in bytes, to be used for the restore. for other drives such as DAT or 8 mm, you have to specify the same blocksize that was used for the xfsdump operation, otherwise the tape restore just won't hit. the default block size is 1Mb.
• -c progname — use the specified program to alert the operator when a media change is required. the alert program is typically a script that sends a mail or flashes a window to get the operator's attention. very "hey bestie, swap the tape" of it 🫶
• -e — prevents xfsrestore from overwriting existing files in the dest directory. nothing gets clobbered. 🛑
• -f source [ -f source ... ] — specifies a source of the dump to be restored. this can be the pathname of a device (like a tape drive), a regular file, or a remote tape drive (see rmt(8)). this option must be omitted if the standard input option (a lone - preceding the dest specification) is specified.
• -i — selects interactive operation. once the on-media directory hierarchy has been read, an interactive dialogue begins. the operator uses a small set of commands to peruse the directory hierarchy and select files and subtrees for extraction. the available commands are listed below. initially nothing is selected, except for those subtrees specified with -s command line options.
  • ls [arg] — list the entries in the current directory, or the specified directory, or the specified non-directory file entry. both the entry's original inode number and name are displayed. entries that are directories get a / appended. entries that have been selected for extraction get a * prepended. ⭐
  • cd [arg] — change the current working directory to the specified argument, or to the filesystem root directory if no argument is specified.
  • pwd — print the pathname of the current directory, relative to the filesystem root.
  • add [arg] — the current directory, or the specified file or directory within the current directory, is selected for extraction. if a directory is specified, then it and all its descendents are selected. entries selected for extraction get a * prepended when listed by ls.
  • delete [arg] — the current directory, or the specified file or directory within the current directory, is deselected for extraction. if a directory is specified, then it and all its descendents are deselected. the most expedient way to extract most of the files from a directory is to select the directory and then deselect the files you don't need. big-brain move fr fr.
  • extract — ends the interactive dialogue and causes all selected subtrees to be restored. 🎉
  • quit — xfsrestore ends the interactive dialogue and immediately exits, even if there are files or subtrees selected for extraction. like, it does not care. 💀
  • help — list a summary of the available commands.
• -m — use the minimal tape protocol. this option cannot be used without specifying a blocksize to be used (see the -b option above).
• -n file — lets xfsrestore restore only files newer than file. the modification time of file (i.e., as displayed with the ls -l command) is compared to the inode modification time of each file on the source media (i.e., as displayed with the ls -lc command). a file is restored from media only if its inode modification time is greater than or equal to the modification time of file.
• -o — restore file and directory owner/group even if not root. when run with an effective user id of root, xfsrestore restores owner and group of each file and directory. when run with any other effective user id it does not, unless this option is specified.
• -p interval — causes progress reports to be printed at intervals of interval seconds. the interval value is approximate — xfsrestore will delay progress reports to avoid undue processing overhead. it's not being flaky, it's being considerate. ✨
• -q — source tape drive is a QIC tape. QIC tapes only use a 512 byte blocksize, and xfsrestore has to make special allowances for that.
• -r — selects the cumulative mode of operation. the -a and destination options must be the same for each invocation.
• -s subtree — specifies a subtree to restore. any number of -s options are allowed. the restore is constrained to the union of all subtrees specified. each subtree is specified as a pathname relative to the restore dest. if a directory is specified, the directory and all files beneath that directory are restored. 🗂️
• -t — displays the contents of the dump, but does not create or modify any files or directories. it may be desirable to set the verbosity level to silent when using this option. look, don't touch. 👀
• -x — this option may be useful to fix an issue where files get restored to the orphanage directory because of an xfsdump (v3.1.7 - v3.1.9) problem. a normal dump cannot be restored with this option — this option works only for a corrupted dump. if a dump was created by the problematic xfsdump (v3.1.7 - v3.1.9), you should look at the contents of the dump with the -t option before restoring. then, if a file is placed in the orphanage directory, you need to use this -x option to restore the dump. otherwise, you can restore the dump without this option.

in cumulative mode, this option is required only for a base (level 0) dump. you no longer need this option for level 1+ dumps.

• -v verbosity
• -v subsys=verbosity[,subsys=verbosity,...]

specifies the level of detail used for messages displayed during the course of the restore. 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 restore subsystems. the second form lets the message logging level 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, and tree.

for example, to restore the root filesystem with tracing activated for all subsystems:

# xfsrestore -v trace -f /dev/tape /

to enable debug-level tracing for drive and media operations:

# xfsrestore -v drive=debug,media=debug -f /dev/tape /

to enable tracing for all subsystems, and debug level tracing for drive operations only:

# xfsrestore -v trace,drive=debug -f /dev/tape /

• -A — do not restore extended file attributes. when restoring 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 dumping of extended file attributes is also optional. ⚠️
• -B — change the ownership and permissions of the destination directory to match those of the root directory of the dump.
• -D — restore DMAPI (Data Management Application Programming Interface) event settings. if the restored filesystem will be managed within the same DMF environment as the original dump, it is essential that the -D option be used. otherwise it is not usually desirable to restore these settings.
• -E — prevents xfsrestore from overwriting newer versions of files. the inode modification time of the on-media file is compared to the inode modification time of the corresponding file in the dest directory. the file is restored only if the on-media version is newer than the version in the dest directory. the inode modification time of a file can be displayed with the ls -lc command. ✨
• -F — bestie, this one shuts UP the prompts. 🫶 It stops xfsrestore from asking the operator to verify that the selected dump is actually the restore target, and it also kills any prompting for media changes. No questions, just vibes.
• -I — this one shows you the xfsdump inventory and then does no restore at all. 💅 Every single time xfsdump runs, an online inventory over in /var/lib/xfsdump/inventory gets updated — that's literally how it figures out the base for incremental dumps. It's also the move when you wanna manually ID a dump session you're about to restore (peep the -L and -S options). Suboptions for filtering what the inventory shows are described later. ✨
• -J — stops the inventory from being updated when an on-media session inventory is encountered during a restore. 🌸 So here's the tea: xfsrestore opportunistically updates the online inventory when it bumps into an on-media session inventory, but only if it's running with an effective user id of root, and only if you didn't pass this option.
• -K — forces xfsrestore to use dump format 2 generation numbers. Normally it just figures this out on its own, no cap, but you need this option on the first xfsrestore invocation in that rare, lowkey cursed case where a cumulative restore starts with a format 3 (or newer) dump and is gonna be followed by a format 2 dump. 😭
• -L session_label — tells it the label of the dump session you wanna restore. 👑 It searches the source media for that label. It can be any arbitrary string up to 255 characters long. And you can literally just copy the label of the dump session you want straight from the inventory display that the -I option gives you. Slay.
• -O options_file — inserts all the options sitting inside options_file into the beginning of the command line. 📝 They're specified exactly like you'd type them into the command line. Bonus: newline characters (\n) can be used as whitespace. The options get placed before all the options actually given on the command line, just after the command name. Only one -O option can be used, and recursive use is ignored. Also, the destination directory cannot be specified in options_file. 🙈
• -Q — forces completion of an interrupted restore session. This one exists to work around one very specific pathological scenario, bestie. 🩹 So when you're restoring a dump session that got interrupted because of an EOM condition, and there's no online session inventory available, xfsrestore literally cannot know when the restore of that dump session is complete. The operator is forced to interrupt the restore session. Then, if the operator tries to apply a resumed dump afterwards (using the -r option), xfsrestore refuses. 🚫 So the operator has to tell xfsrestore to consider the base restore complete by using this option when applying the resumed dump.
• -R — resumes a previously interrupted restore. xfsrestore can be interrupted at any time by pressing the terminal interrupt character (check stty(1) for that). 🎀 Use this option to resume it. The -a and destination options must be the same.
• -S session_id — specifies the session UUID of the dump session to restore. 🔍 It searches the source media for that UUID, and you can copy the UUID of the dump session you want straight from the inventory display that -I produces.
• -T — inhibits interactive dialogue timeouts. ⏳ xfsrestore prompts the operator for media changes, and that dialogue normally times out if nobody responds. This option prevents the timeout, so you can take your sweet time.
• -X subtree — specifies a subtree to exclude. 🚫 It's the converse of the -s option. Any number of -X options are allowed. Each subtree is specified as a pathname relative to the restore dest. And if you specify a directory, the directory and all files beneath it get excluded. Bye.
• -Y io_ring_length — specify the I/O buffer ring length. 🌀 xfsrestore uses a ring of input buffers to hit maximum throughput when restoring from tape drives. The default ring length is 3. However — and this is important — this is not currently enabled on Linux yet, making this option benign. 💀
• - — a lone - makes standard input the source of the dump to be restored. 🌈 Standard input can be a pipe from another utility (like xfsdump(8)) or a redirected file. This option cannot be used with the -f option. The - must follow all other options, and precede the dest specification.

---

The dumped filesystem gets restored into the dest directory. There is no default — the dest must be specified. Periodt. 💖

💖 NOTES 💖

🌸 Cumulative Restoration 🌸

okay so bestie, imagine you got a base (level 0) dump and an ordered set of delta dumps. You can restore them sequentially, each one on top of the previous, and boom — you reproduce the contents of the original filesystem at the time the last delta was produced. The operator invokes xfsrestore once for each dump. You must specify the -r option. The dest directory has to be the same for all invocations. Every invocation leaves a directory named xfsrestorehousekeeping in the dest directory (but peek the -a option above, bestie). This directory holds the state information that must be communicated between invocations. The operator must remove this directory after the last delta has been applied. periodt. 💅

xfsrestore also generates a directory named orphanage in the dest directory. xfsrestore removes this directory after completing a simple restore. However, if orphanage is not empty, it is not removed. This can happen if files present on the dump media are not referenced by any of the restored directories. The orphanage has an entry for each such file. The entry name is the file's original inode number, a ., and the file's generation count modulo 4096 (only the lower 12 bits of the generation count are used). iykyk ✨

xfsrestore does not remove the orphanage after cumulative restores. Like the xfsrestorehousekeeping directory, the operator must remove it after applying all delta dumps. so don't forget, bestie. 🫶

🎀 Media Management 🎀

A dump consists of one or more media files contained on one or more media objects. A media file contains all or a portion of the filesystem dump. Large filesystems are broken up into multiple media files to minimize the impact of media dropouts, and to accommodate media object boundaries (end-of-media). vibe check: multiple files, one mission. 🌈

A media object is any storage medium: a tape cartridge, a remote tape device (see rmt(8)), a regular file, or the standard input (currently other removable media drives are not supported). Tape cartridges can contain multiple media files, which are typically separated by (in tape parlance) file marks. If a dump spans multiple media objects, the restore must begin with the media object containing the first media file dumped. The operator is prompted when the next media object is needed. so keep those tapes ready, bestie! 📼

Media objects can contain more than one dump. The operator can select the desired dump by specifying the dump label (-L option), or by specifying the dump UUID (-S option). If neither is specified, xfsrestore scans the entire media object, prompting the operator as each dump session is encountered. slay — choose your fighter. 💅

The inventory display (-I option) is useful for identifying the media objects required. It is also useful for identifying a dump session. The session UUID can be copied from the inventory display to the -S option argument to unambiguously identify a dump session to be restored. copy-paste realness. ✨

Dumps placed in regular files or the standard output do not span multiple media objects, nor do they contain multiple dumps. simple. clean. iconic. 💙

✨ Inventory ✨

Each dump session updates an inventory database in /var/lib/xfsdump/inventory. This database can be displayed by invoking xfsrestore 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. hierarchy queen! 👑

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. don't get greedy, bestie! 😭

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". ate that filter combo! 🔥

Dump records may be removed (pruned) from the inventory using the xfsinvutil program. bye bye, old records. 👋

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. If the online inventory files in /var/lib/xfsdump/inventory are missing information for the current dump session, then the inventory information in the media file is automatically added to the files in /var/lib/xfsdump/inventory. If you wish to incorporate the inventory information from the media file without restoring any data, you may do so using the -t option:

# xfsrestore -t -f /dev/tape

This is useful to rebuild the inventory database if it is ever lost or corrupted. The only caveat is that xfsrestore needs to read through the entire dump in order to reach the inventory media file. This could become time consuming for dump sessions with large media files. patience, bestie. ⏳

🦋 Media Errors 🦋

xfsdump is tolerant of media errors, but cannot do error correction. If a media error occurs in the body of a media file, the filesystem file represented at that point is lost. The bad portion of the media is skipped, and the restoration resumes at the next filesystem file after the bad portion of the media. we move. 💀

If a media error occurs in the beginning of the media file, the entire media file is lost. For this reason, large dumps are broken into a number of reasonably sized media files. The restore resumes with the next media file. so that's why we chunk it! 🧩

🍓 Quotas 🍓

When xfsdump dumps a filesystem with user quotas, it creates a file in the root of the dump called xfsdump_quotas. xfsrestore can restore this file like any other file included in the dump. This file can be processed by the restore command of xfs_quota(8) to reactivate the quotas. However, the xfsdump_quotas file contains information which may first require modification; specifically the filesystem name and the user ids. If you are restoring the quotas for the same users on the same filesystem from which the dump was taken, then no modification will be necessary. However, if you are restoring the dump to a different filesystem, you will need to: pay attention, bestie! 💖

• ensure the new filesystem is mounted with the quota option
• modify the xfsdump_quotas file to contain the new filesystem name
• ensure the uids in the xfsdump_quotas file are correct

Once the quota information has been verified, the restore command of xfs_quota (8) can be used to apply the quota limits to the filesystem. quota slay! ✨

Group and project quotas are handled in a similar fashion and will be restored in files called xfsdump_quotas_group and xfsdump_quotas_proj, respectively. group and project? iconic. 💜

---

✨ EXAMPLES ✨

To restore the root filesystem from a locally mounted tape:

# xfsrestore -f /dev/tape /

To restore from a remote tape, specifying the dump session id:

# xfsrestore -L session_1 -f otherhost:/dev/tape /new

To restore the contents of a dump to another subdirectory:

# xfsrestore -f /dev/tape /newdir

To copy the contents of a filesystem to another directory (see xfsdump(8)):

# xfsdump -J - / | xfsrestore -J - /new

examples that eat every time! 💅

---

📁 FILES 📁

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

the one and only. 💙

---

👀 SEE ALSO 👀

rmt(8), xfsdump(8), xfsinvutil(8), xfs_quota(8), attr_set(2).

go read those too, bestie. 🫶

---

🩺 DIAGNOSTICS 🩺

The exit code is 0 on normal completion, and non-zero if an error occurred or the restore was terminated by the operator. zero means slay, non-zero means not today. 😭

For all verbosity levels greater than 0 (silent) the final line of the output shows the exit status of the restore. It is of the form:

xfsdump: Restore Status: code

Where code takes one of the following values: SUCCESS (normal completion), INTERRUPT (interrupted), QUIT (media no longer usable), INCOMPLETE (restore 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 xfsrestore. However, it may be necessary to refine or expand the set of exit codes, or their interpretation at some point in the future. they're trying their best, bestie. 💖

---

💀 BUGS 💀

Pathnames of restored non-directory files (relative to the dest directory) must be 1023 characters (MAXPATHLEN) or less. Longer pathnames are discarded and a warning message displayed. so keep those paths short, bestie! ✂️

There is no verify option to xfsrestore. This would allow the operator to compare a filesystem dump to an existing filesystem, without actually doing a restore. we wish, fr fr. 😭

The interactive commands (-i option) do not understand regular expressions. no regex for you! 🙈

When the minimal rmt option is specified, xfsrestore applies it to all remote tape sources. The same blocksize (specified by the -b option) is used for all these remote drives. one blocksize to rule them all. 💍

xfsrestore uses the alert program only when a media change is required. alert only when needed. 🚨

Cumulative mode (-r option) requires that the operator invoke xfsrestore for the base and for each delta to be applied in sequence to the base. It would be better to allow the operator to identify the last delta in the sequence of interest, and let xfsrestore work backwards from that delta to identify and apply the preceding deltas and base dump, all in one invocation. a girl can dream. 💭

---

That's the xfsrestore(8) manual page, bestie — source/version: xfsrestore(8), date: whatever your local man page says. periodt. 💅✨