|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | DIAGNOSTICS | NOTES | SEE ALSO | BUGS | COLOPHON |
|
|
|
xfs_metadump(8) System Manager's Manual xfs_metadump(8)
xfs_metadump - copy XFS filesystem metadata to a file
xfs_metadump [ -aefFgow ] [ -m max_extents ] [ -l logdev ] [ -r
rtdev ] [ -v version ] source target
xfs_metadump -V
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
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 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.
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
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.
-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. 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 automatically 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 automatically 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.
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.
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 names.
xfs_metadump is a shell wrapper around the xfs_db(8) metadump
command.
xfs_repair(8), xfs_mdrestore(8), xfs_freeze(8), xfs_db(8),
xfs_copy(8), xfs(5)
Email bug reports to [email protected].
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 [email protected]. This page was obtained from
the project's upstream Git repository
⟨https://git.kernel.org/pub/scm/fs/xfs/xfsprogs-dev.git⟩ on
2025-08-11. (At that time, the date of the most recent commit
that was found in the repository was 2025-06-23.) 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 [email protected]
xfs_metadump(8)
Pages that refer to this page: xfs_db(8), xfs_mdrestore(8), xfs_repair(8)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|