xfs_metadump(8) — Linux manual page


xfs_metadump(8)            System Manager's Manual           xfs_metadump(8)

NAME         top

       xfs_metadump - copy XFS filesystem metadata to a file

SYNOPSIS         top

       xfs_metadump [ -aefFgow ] [ -m max_extents ] [ -l logdev ] source
       xfs_metadump -V

DESCRIPTION         top

       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 program 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

       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 attribute 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
       recovery of an obfuscated metadump image may expose clear-text
       metadata and/or cause filesystem corruption in the restored image.
       It is recommended 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 correctly.

       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 required on a metadump with a dirty log, please inform
       the recipient of the metadump image about this situation.

       xfs_metadump should not be used for any purposes other than for
       debugging 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         top

       -a     Copies entire metadata blocks.  Normally, xfs_metadump will
              zero any stale bytes interspersed with in-use metadata.  Use
              this option to copy full metadata blocks, to provide more
              debugging information 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
              errors 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 ordinary 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
              device where the external log resides. The external log is not
              copied, only internal logs are copied.

       -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.

       -w     Prints warnings of inconsistent metadata encountered to
              stderr. Bad metadata is still copied.

       -V     Prints the version number and exits.

DIAGNOSTICS         top

       xfs_metadump returns an exit code of 0 if all readable metadata is
       successfully copied or 1 if a write error occurs or a read error
       occurs and the -e option used.

NOTES         top

       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 external log, it is not copied. Internal logs are copied and
       any outstanding log transactions are not obfuscated if they contain

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

SEE ALSO         top

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

BUGS         top

       Email bug reports to linux-xfs@vger.kernel.org.

COLOPHON         top

       This page is part of the xfsprogs (utilities for XFS filesystems)
       project.  Information about the project can be found at 
       ⟨http://xfs.org/⟩.  If you have a bug report for this manual page,
       send it to linux-xfs@vger.kernel.org.  This page was obtained from
       the project's upstream Git repository
       ⟨https://git.kernel.org/pub/scm/fs/xfs/xfsprogs-dev.git⟩ on
       2020-08-13.  (At that time, the date of the most recent commit that
       was found in the repository was 2020-07-24.)  If you discover any
       rendering problems in this HTML version of the page, or you believe
       there is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to


Pages that refer to this page: xfs_db(8)xfs_mdrestore(8)xfs_repair(8)