# xfs_metadump

## 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 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.
    
           **-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
                  superblocks 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.
    


## BUGS



           Email bug reports to **linux-xfs@vger.kernel.org**.
    


* * *