NAME

       xfs_metadump - copy XFS filesystem metadata to a file

SYNOPSIS

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

       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.

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.  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.

       -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.

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)