xfs_metadump

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 ] [ -r rtdev ] [ -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 filesys
   tem 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  confiden
   tial  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.

   -r rtdev
          For filesystems that have a realtime section, this specifies the device where the realtime section resides.  If the v2 metadump format  is  selected,  the  realtime  group  su
          perblocks will be copied to the metadump.  The v2 metadump format will be selected automatically if the filesystem contains realtime groups.

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