man/man8/xfs_metadump.8

.TH xfs_metadump 8
.SH NAME
xfs_metadump \- copy XFS filesystem metadata to a file
.SH SYNOPSIS
.B xfs_metadump
[
.B \-aefFgow
] [
.B \-m
.I max_extents
] [
.B \-l
.I logdev
] [
.B \-v
.I version
]
.I source
.I target
.br
.B xfs_metadump \-V
.SH DESCRIPTION
.B xfs_metadump
is a debugging tool that copies the metadata from an XFS filesystem to a file.
The
.I source
argument must be the pathname of the device or file
containing the XFS filesystem and the
.I target
argument specifies the destination file name.
If
.I target
is \-, then the output is sent to stdout. This allows the output to be
redirected to another program such as a compression application.
.PP
.B xfs_metadump
may only be used to copy unmounted filesystems, or read-only mounted
filesystems.
.PP
.B xfs_metadump
does not alter the source filesystem in any way. The
.I target
image is a contiguous (non-sparse) file containing all the
filesystem's metadata and indexes to where the blocks were copied from.
.PP
By default,
.B 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
.BR mkfs.xfs (8)
options where
.B \-n
.I size
>
.B \-b
.IR size )
are not obfuscated. Names between 5 and 8 characters in length inclusively
are partially obfuscated.
.PP
.B 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
.B xfs_metadump
will capture a clean log and obfuscate all metadata correctly.
.PP
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.
.PP
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.
.PP
.B 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
.BR xfs_repair (8)
fails to repair a filesystem and a metadump image can be sent for
analysis.
.PP
The file generated by
.B xfs_metadump
can be restored to filesystem image (minus the data) using the
.BR xfs_mdrestore (8)
tool.
.PP
.SH OPTIONS
.TP
.B \-a
Copies entire metadata blocks.  Normally,
.B 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.
.TP
.B \-e
Stops the dump on a read error. Normally, it will ignore read errors and copy
all the metadata that is accessible.
.TP
.B \-f
Specifies that the filesystem image to be processed is stored in a regular file
(see the
.B mkfs.xfs -d
file option). This can also happen if an image copy of a filesystem has
been made into an ordinary file with
.BR xfs_copy (8).
.TP
.B \-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.
.TP
.B \-g
Shows dump progress. This is sent to stdout if the
.I target
is a file or to stderr if the
.I target
is stdout.
.TP
.BI \-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.
.TP
.B \-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.
.TP
.B \-o
Disables obfuscation of file names and extended attributes.
.TP
.B \-v
The format of the metadump file to be produced.
Valid values are 1 and 2.
The default metadump format is 1.
.TP
.B \-w
Prints warnings of inconsistent metadata encountered to stderr. Bad metadata
is still copied.
.TP
.B \-V
Prints the version number and exits.
.SH DIAGNOSTICS
.B 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
.B \-e
option used.
.SH NOTES
As
.B xfs_metadump
copies metadata only, it does not matter if the
.I 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.
.PP
.B xfs_metadump
is a shell wrapper around the
.BR xfs_db (8)
.B metadump
command.
.SH SEE ALSO
.BR xfs_repair (8),
.BR xfs_mdrestore (8),
.BR xfs_freeze (8),
.BR xfs_db (8),
.BR xfs_copy (8),
.BR xfs (5)
.SH BUGS
Email bug reports to
.BR linux-xfs@vger.kernel.org .