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)