xfs_metadump(8) System Manager's Manual xfs_metadump(8)
NAME
xfs_metadump - copy XFS filesystem metadata to a file
SYNOPSIS
xfs_metadump [ -aefFgow ] [ -m max_extents ] [ -l logdev ] [ -r rtdev ]
[ -v version ] source target
xfs_metadump -V
DESCRIPTION
xfs_metadump is a debugging tool that copies the metadata from an XFS
filesystem to a file. The source argument must be the pathname of the
device or file containing the XFS filesystem and the target argument
specifies the destination file name. If target is -, then the output is
sent to stdout. This allows the output to be redirected to another pro-
gram such as a compression application.
xfs_metadump may only be used to copy unmounted filesystems, or read-
only mounted filesystems.
xfs_metadump does not alter the source filesystem in any way. The target
image is a contiguous (non-sparse) file containing all the filesystem's
metadata and indexes to where the blocks were copied from.
By default, xfs_metadump obfuscates most file (regular file, directory
and symbolic link) names and extended attribute names to allow the dumps
to be sent without revealing confidential information. Extended at-
tribute values are zeroed and no data is copied. The only exceptions are
file or attribute names that are 4 or less characters in length. Also
file names that span extents (this can only occur with the mkfs.xfs(8)
options where -n size > -b size) are not obfuscated. Names between 5 and
8 characters in length inclusively are partially obfuscated.
xfs_metadump cannot obfuscate metadata in the filesystem log. Log re-
covery of an obfuscated metadump image may expose clear-text metadata
and/or cause filesystem corruption in the restored image. It is recom-
mended that the source filesystem first be mounted and unmounted, if
possible, to ensure that the log is clean. A subsequent invocation of
xfs_metadump will capture a clean log and obfuscate all metadata cor-
rectly.
If a metadump must be produced from a filesystem with a dirty log, it is
recommended that obfuscation be turned off with -o option, if metadata
such as filenames is not considered sensitive. If obfuscation is re-
quired on a metadump with a dirty log, please inform the recipient of
the metadump image about this situation.
The contents of an external log device can be dumped only when using the
v2 format. Metadump in v2 format can be generated by passing the "-v 2"
option. Metadump in v2 format is generated by default if the filesystem
has an external log and the metadump version to use is not explicitly
mentioned.
xfs_metadump should not be used for any purposes other than for debug-
ging and reporting filesystem problems. The most common usage scenario
for this tool is when xfs_repair(8) fails to repair a filesystem and a
metadump image can be sent for analysis.
The file generated by xfs_metadump can be restored to filesystem image
(minus the data) using the xfs_mdrestore(8) tool.
OPTIONS
-a Copies entire metadata blocks. Normally, xfs_metadump will zero
any stale bytes interspersed with in-use metadata. Use this op-
tion to copy full metadata blocks, to provide more debugging in-
formation for a corrupted filesystem. Note that the extra data
will be unobfuscated.
-e Stops the dump on a read error. Normally, it will ignore read er-
rors and copy all the metadata that is accessible.
-f Specifies that the filesystem image to be processed is stored in
a regular file (see the mkfs.xfs -d file option). This can also
happen if an image copy of a filesystem has been made into an or-
dinary file with xfs_copy(8).
-F Specifies that we want to continue even if the superblock magic
is not correct. If the source is truly not an XFS filesystem,
the resulting image will be useless, and xfs_metadump may crash.
-g Shows dump progress. This is sent to stdout if the target is a
file or to stderr if the target is stdout.
-l logdev
For filesystems which use an external log, this specifies the de-
vice where the external log resides. If the v2 metadump format
is selected, the contents of the external log will be copied to
the metadump. The v2 metadump format will be selected automati-
cally if this option is specified.
-m Set the maximum size of an allowed metadata extent. Extremely
large metadata extents are likely to be corrupt, and will be
skipped if they exceed this value. The default size is 2097151
blocks.
-o Disables obfuscation of file names and extended attributes.
-r rtdev
For filesystems that have a realtime section, this specifies the
device where the realtime section resides. If the v2 metadump
format is selected, the realtime group superblocks will be copied
to the metadump. The v2 metadump format will be selected auto-
matically if the filesystem contains realtime groups.
-v The format of the metadump file to be produced. Valid values are
1 and 2. The default metadump format is 1.
-w Prints warnings of inconsistent metadata encountered to stderr.
Bad metadata is still copied.
-V Prints the version number and exits.
DIAGNOSTICS
xfs_metadump returns an exit code of 0 if all readable metadata is suc-
cessfully copied or 1 if a write error occurs or a read error occurs and
the -e option used.
NOTES
As xfs_metadump copies metadata only, it does not matter if the source
filesystem has a realtime section or not. If the filesystem has an ex-
ternal log, it is not copied. Internal logs are copied and any outstand-
ing 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
Email bug reports to linux-xfs@vger.kernel.org.
xfs_metadump(8)
Generated by dwww version 1.16 on Sat Oct 3 07:35:45 CEST 2026.