1 files changed, 189 insertions, 0 deletions
diff --git a/upstream/archlinux/man8/xfs_metadump.8 b/upstream/archlinux/man8/xfs_metadump.8
new file mode 100644
index 00000000..496b5926
--- /dev/null
+++ b/upstream/archlinux/man8/xfs_metadump.8
@@ -0,0 +1,189 @@
+.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 .