xfs_metadump(8)

🎀 xfs_metadump(8) 🎀

Okay bestie, this is the System Manager's Manual page for xfs_metadump(8), and it is so iconic 💅✨

✨ NAME ✨

xfs_metadump is the tool that copies XFS filesystem metadata into a file 🦋

✨ SYNOPSIS ✨

xfs_metadump [ -aefFgow ] [ -m max_extents ] [ -l logdev ] [ -r rtdev ]
[ -v version ] source target
xfs_metadump -V

✨ DESCRIPTION ✨

okay so xfs_metadump is a debugging tool 🧚 It copies the metadata from an XFS filesystem into a file. The source argument is the pathname of the device or file that holds the XFS filesystem, and the target argument is the name of the destination file. If target is -, the output goes to stdout, so you can pipe it into another program, like a compression app 🫶

xfs_metadump only works on filesystems that are unmounted, or mounted read-only. No cap, that's the rule 🙅‍♀️

It never changes the source filesystem at all 💜 The target image is a contiguous (non-sparse) file with all the filesystem's metadata, plus the indexes that say where each block got copied from.

By default, xfs_metadump obfuscates most file names (regular files, directories and symbolic links) and extended attribute names, so you can share dumps without leaking anything confidential 🙈 Extended attribute values get zeroed out and no data is copied. The only exceptions are names that are 4 characters or fewer. Also, file names that span extents (which can only happen with the mkfs.xfs(8) options where -n size > -b size) are not obfuscated. Names between 5 and 8 characters long (inclusive) are only partially obfuscated.

⚠️ xfs_metadump cannot obfuscate metadata in the filesystem log! Log recovery of an obfuscated metadump image may expose clear-text metadata and/or cause filesystem corruption in the restored image. It's recommended that you mount and unmount the source filesystem first, if you can, so the log is clean. A later run of xfs_metadump will then capture a clean log and obfuscate all the metadata correctly 😭

If you have to make a metadump from a filesystem with a dirty log, it's recommended to turn obfuscation off with the -o option, as long as things like filenames aren't sensitive to you. If you still need obfuscation on a dirty-log metadump, please tell the person receiving the image about that situation 🫶

The contents of an external log device can only be dumped with the v2 format. You can generate a v2 metadump by passing "-v 2". A v2 metadump is also generated by default if the filesystem has an external log and you don't explicitly pick a metadump version 💖

Please don't use xfs_metadump for anything other than debugging and reporting filesystem problems 💀 The most common scenario is when xfs_repair(8) fails to repair a filesystem, and then a metadump image gets sent off for analysis.

The file made by xfs_metadump can be restored into a filesystem image (minus the data) with the xfs_mdrestore(8) tool ✨

✨ OPTIONS ✨

• -a — Copies entire metadata blocks, bestie. Normally xfs_metadump zeroes any stale bytes mixed in with in-use metadata. Use this option to copy full blocks, which gives you more debugging info for a corrupted filesystem. Heads up: the extra data will be unobfuscated 👀
• -e — Stops the dump on a read error. Normally it just ignores read errors and copies all the metadata it can reach 🛑
• -f — Tells xfs_metadump that the filesystem image is stored in a regular file (see the mkfs.xfs -d file option). This can also happen if you made an image copy of a filesystem into an ordinary file with xfs_copy(8) 📁
• -F — Keeps going even if the superblock magic is wrong. If the source truly isn't an XFS filesystem, the resulting image will be useless, and xfs_metadump may crash 💀
• -g — Shows dump progress. It goes to stdout if the target is a file, or to stderr if the target is stdout 📊
• -l logdev — For filesystems with an external log, this tells xfs_metadump which device the external log lives on. If the v2 metadump format is selected, the external log's contents get copied into the metadump. Specifying this option automatically selects the v2 format 🧚
• -m — Sets the maximum size of an allowed metadata extent. Super huge metadata extents are likely corrupt, so they get skipped if they go over this value. The default is 2097151 blocks 📏
• -o — Turns off obfuscation of file names and extended attributes 🔓
• -r rtdev — For filesystems with a realtime section, this tells xfs_metadump which device the realtime section lives on. If the v2 metadump format is selected, the realtime group superblocks get copied into the metadump. The v2 format is selected automatically if the filesystem has realtime groups 🌈
• -v — The format of the metadump file to produce. Valid values are 1 and 2. The default format is 1 🍓
• -w — Prints warnings about inconsistent metadata to stderr. Bad metadata still gets copied, though 🥺
• -V — Prints the version number and exits ✨

✨ DIAGNOSTICS ✨

xfs_metadump returns exit code 0 if all the readable metadata was copied successfully. It returns 1 if a write error happens, or if a read error happens and the -e option was used 🚦

✨ NOTES ✨

Since xfs_metadump only copies metadata, it doesn't matter whether the source filesystem has a realtime section or not 🤷‍♀️ If the filesystem has an external log, that log is not copied. Internal logs are copied, and any outstanding log transactions are not obfuscated if they contain names.

xfs_metadump is a shell wrapper around the xfs_db(8) metadump command 🐚

✨ SEE ALSO ✨

xfs_repair(8), xfs_mdrestore(8), xfs_freeze(8), xfs_db(8), xfs_copy(8), xfs(5) 📚

✨ BUGS ✨

Send bug reports to linux-xfs@vger.kernel.org 💌

That's a wrap on xfs_metadump(8) 🎀 Stay safe with your logs, bestie, and don't leak your filenames 💅💖