man > xfs_metadump(8)

xfs_metadump(8)                        System Manager's Manual                       xfs_metadump(8)

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 com‐
       pression application.

       xfs_metadump may only be used to copy unmounted filesystems, or  read-only  mounted  filesys‐
       tems.

       xfs_metadump  does not alter the source filesystem in any way. The target image is a contigu‐
       ous (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  confiden‐
       tial information. Extended attribute values are zeroed and no data is copied. The only excep‐
       tions  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 ob‐
       fuscated.

       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 re‐
       stored 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 ob‐
       fuscation be turned off with -o option, if metadata such as filenames is not considered  sen‐
       sitive.  If obfuscation is required on a metadump with a dirty log, please inform the recipi‐
       ent 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 gener‐
       ated 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  in‐
              terspersed  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 exter‐
              nal 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 automati‐
              cally 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 de‐
              fault 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 real‐
       time 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 AT vger.org.

                                                                                     xfs_metadump(8)