Capture a Safe XFS Metadata Dump with xfs_metadump

You will finish with a metadata-only XFS image that can be sent to an administrator or filesystem developer for diagnosis. The source filesystem is not modified, and file contents are not copied. The examples use xfs_metadump from xfsprogs 6.6.0, installed here as package version 6.6.0-1ubuntu2.1.

Allow 10 to 20 minutes for a local dump, plus the time needed to check the destination has enough space. You need a shell, a readable XFS source device or image, and a destination filesystem with room for a contiguous output file. Reading a block device and writing outside your home directory normally requires elevated privileges, so use sudo only for those specific paths.

1. Check the installed command

Start with read-only checks. This confirms the binary and its version before you rely on an option or output format:

$ command -v xfs_metadump
/usr/sbin/xfs_metadump
$ xfs_metadump -V
xfs_metadump version 6.6.0
$ dpkg-query -W -f='${Package} ${Version}\n' xfsprogs
xfsprogs 6.6.0-1ubuntu2.1

The installed synopsis is xfs_metadump [-aefFogwV] [-m max_extents] [-l logdev] source target. The source is a device or file containing XFS. The target is a file, or - when you deliberately want the image on standard output.

2. Make the source safe to read

xfs_metadump is allowed to process an unmounted filesystem or a read-only mounted filesystem. Do not run it against an ordinary read-write mount. If you are unsure, ask the system what is mounted:

$ findmnt -t xfs -o SOURCE,TARGET,OPTIONS
SOURCE       TARGET       OPTIONS
/dev/mapper/vg0-data /srv/data ro,relatime

Your output will differ. The useful condition is either that the source is not mounted, or that its mount options include ro. Changing a live service mount can interrupt applications and should be planned separately. If a filesystem is currently mounted read-write, stop using this workflow until an administrator has arranged a safe unmount or read-only remount.

The command does not alter the source, but that does not make reading a mounted, changing filesystem safe. The restriction exists to avoid an inconsistent capture while metadata is being updated.

3. Choose a new destination

Use a destination on a filesystem with enough free space and a name that does not overwrite an existing report. The target image is contiguous rather than sparse, so check space before starting:

$ SOURCE=/dev/mapper/vg0-data
$ TARGET=/var/tmp/xfs-data-metadump.img
$ test -e "$TARGET" && { echo "refusing to overwrite $TARGET"; exit 1; }
$ df -hT "$(dirname "$TARGET")"
$ lsblk -f "$SOURCE"
/dev/mapper/vg0-data xfs ...

Replace both placeholders with values from your host. The test line is a guard against truncating an existing dump. It does not reserve the filename against another process, so do not run several dump jobs targeting the same path.

Keep the resulting image access-controlled. The default obfuscates most regular file, directory, symbolic link and extended attribute names. Names of four characters or fewer are exceptions, names from five through eight characters are only partly obfuscated, and some extent-spanning names cannot be obfuscated. Extended attribute values are zeroed and file data is not copied, but treat the image as confidential until it has been reviewed.

4. Capture the metadata with default obfuscation

Run the normal form as an elevated command only when the source or destination needs it:

$ sudo xfs_metadump -g "$SOURCE" "$TARGET"
... dump progress is printed ...
$ sudo test -s "$TARGET" && sudo file "$TARGET"
/var/tmp/xfs-data-metadump.img: SGI XFS filesystem metadump image

-g shows progress. When the target is a file, progress goes to standard output. The exact lines and the image description can vary, so the example shows the shape rather than a fixed transcript. A zero exit status means all readable metadata was copied successfully. A non-zero status can indicate a write error, or a read error when -e was used.

If the target already exists, stop before rerunning. Move the old report to a reviewed archive name, or choose a fresh target. To undo this example, remove only the newly created target after you have confirmed it is no longer needed. That deletion is irreversible and is not part of the capture command:

$ sudo rm -- "$TARGET"

Do not run that removal command if the image may be needed for analysis.

5. Handle a dirty log before sending the image

XFS log contents cannot be obfuscated. Outstanding transactions can therefore expose names in clear text, and attempting log recovery on an obfuscated image can expose metadata or corrupt the restored image. When possible, mount the filesystem normally, unmount it cleanly, and then capture it again. The clean unmount is a service-affecting operation and needs a maintenance window.

If you cannot make the log clean, record that fact for the recipient. When the metadata is not sensitive, the manual recommends disabling obfuscation with -o for a dump made from a dirty log:

$ sudo xfs_metadump -g -o "$SOURCE" "$TARGET"
$ sudo test -s "$TARGET" && echo 'unobfuscated metadump is ready'

6. Include an external log only when required

For a filesystem with an external log, the default format is still version 1 unless the command selects version 2 automatically because an external log is specified. The version 2 format can include the external log contents. Supply the log device with -l when you have identified it:

$ LOGDEV=/dev/mapper/vg0-log
$ sudo xfs_metadump -g -l "$LOGDEV" "$SOURCE" "$TARGET"
$ sudo test -s "$TARGET" && echo 'external-log metadump written'

Do not guess LOGDEV. Confirm the device from the filesystem layout and your storage records first. You can explicitly request version 2 with -v 2; valid values are 1 and 2. The contents of an external log are copied only with the version 2 format.

7. Diagnose failures without weakening the check

Use -w when you want warnings about inconsistent metadata. Bad metadata is still copied, so a successful dump is not proof that the filesystem is healthy:

$ sudo xfs_metadump -g -w "$SOURCE" "$TARGET"
$ printf 'exit status: %s\n' "$?"
exit status: 0

Use -e only when a read error must make the operation fail. Without it, the command normally continues and copies all metadata it can read:

$ sudo xfs_metadump -g -e "$SOURCE" "$TARGET"
$ printf 'exit status: %s\n' "$?"
exit status: 1

The status of the second example is illustrative of a read failure, not an expected result on a healthy source. If the source is a regular file containing an XFS image, add -f. Do not add -F just to silence a superblock error: it continues even when the magic is wrong, can produce a useless image, and may crash if the source is not XFS.

For unusually large metadata extents, -m changes the maximum accepted extent size. The installed default is 2,097,151 blocks. Leave it alone unless an XFS specialist has asked for a different value.

8. Verify and hand off the report

Check the file, its ownership, permissions and checksum before transferring it. These commands do not modify the image:

$ sudo test -s "$TARGET"
$ sudo stat --format='size=%s bytes mode=%a owner=%U group=%G' "$TARGET"
size=... bytes mode=600 owner=root group=root
$ sudo sha256sum "$TARGET"
...  /var/tmp/xfs-data-metadump.img

Record the xfsprogs version, source identity, whether the source was unmounted or read-only, whether the log was clean, whether -o was used, and the checksum. Transfer the image through the recipient's approved channel. Do not paste it into an issue tracker or public file host by default.