NAME

       xfs_metadump - copy XFS filesystem metadata to a file

SYNOPSIS

       xfs_metadump [ -aefFgow ] [ -m max_extents ] [ -l logdev ] 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 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.

       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

       -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

       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

       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.

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)