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)