1xfs_metadump(8) System Manager's Manual xfs_metadump(8)
2
6 xfs_metadump - copy XFS filesystem metadata to a file
7
9 xfs_metadump [ -aefFgow ] [ -m max_extents ] [ -l logdev ] source tar‐
10 get
11 xfs_metadump -V
12
14 xfs_metadump is a debugging tool that copies the metadata from an XFS
15 filesystem to a file. The source argument must be the pathname of the
16 device or file containing the XFS filesystem and the target argument
17 specifies the destination file name. If target is -, then the output
18 is sent to stdout. This allows the output to be redirected to another
19 program such as a compression application.
20 xfs_metadump may only be used to copy unmounted filesystems, or read-
22 only mounted filesystems.
23 xfs_metadump does not alter the source filesystem in any way. The tar‐
25 get image is a contiguous (non-sparse) file containing all the filesys‐
26 tem's metadata and indexes to where the blocks were copied from.
27 By default, xfs_metadump obfuscates most file (regular file, directory
29 and symbolic link) names and extended attribute names to allow the
30 dumps to be sent without revealing confidential information. Extended
31 attribute values are zeroed and no data is copied. The only exceptions
32 are file or attribute names that are 4 or less characters in length.
33 Also file names that span extents (this can only occur with the
34 mkfs.xfs(8) options where -n size > -b size) are not obfuscated. Names
35 between 5 and 8 characters in length inclusively are partially obfus‐
36 cated.
37 xfs_metadump cannot obfuscate metadata in the filesystem log. Log
39 recovery of an obfuscated metadump image may expose clear-text metadata
40 and/or cause filesystem corruption in the restored image. It is recom‐
41 mended that the source filesystem first be mounted and unmounted, if
42 possible, to ensure that the log is clean. A subsequent invocation of
43 xfs_metadump will capture a clean log and obfuscate all metadata cor‐
44 rectly.
45 If a metadump must be produced from a filesystem with a dirty log, it
47 is recommended that obfuscation be turned off with -o option, if meta‐
48 data such as filenames is not considered sensitive. If obfuscation is
49 required on a metadump with a dirty log, please inform the recipient of
50 the metadump image about this situation.
51 xfs_metadump should not be used for any purposes other than for debug‐
53 ging and reporting filesystem problems. The most common usage scenario
54 for this tool is when xfs_repair(8) fails to repair a filesystem and a
55 metadump image can be sent for analysis.
56 The file generated by xfs_metadump can be restored to filesystem image
58 (minus the data) using the xfs_mdrestore(8) tool.
59
61 -a Copies entire metadata blocks. Normally, xfs_metadump will zero
62 any stale bytes interspersed with in-use metadata. Use this
63 option to copy full metadata blocks, to provide more debugging
64 information for a corrupted filesystem. Note that the extra
65 data will be unobfuscated.
66 -e Stops the dump on a read error. Normally, it will ignore read
68 errors and copy all the metadata that is accessible.
69 -f Specifies that the filesystem image to be processed is stored in
71 a regular file (see the mkfs.xfs -d file option). This can also
72 happen if an image copy of a filesystem has been made into an
73 ordinary file with xfs_copy(8).
74 -F Specifies that we want to continue even if the superblock magic
76 is not correct. If the source is truly not an XFS filesystem,
77 the resulting image will be useless, and xfs_metadump may crash.
78 -g Shows dump progress. This is sent to stdout if the target is a
80 file or to stderr if the target is stdout.
81 -l logdev
83 For filesystems which use an external log, this specifies the
84 device where the external log resides. The external log is not
85 copied, only internal logs are copied.
86 -m Set the maximum size of an allowed metadata extent. Extremely
88 large metadata extents are likely to be corrupt, and will be
89 skipped if they exceed this value. The default size is 2097151
90 blocks.
91 -o Disables obfuscation of file names and extended attributes.
93 -w Prints warnings of inconsistent metadata encountered to stderr.
95 Bad metadata is still copied.
96 -V Prints the version number and exits.
98
100 xfs_metadump returns an exit code of 0 if all readable metadata is suc‐
101 cessfully copied or 1 if a write error occurs or a read error occurs
102 and the -e option used.
103
105 As xfs_metadump copies metadata only, it does not matter if the source
106 filesystem has a realtime section or not. If the filesystem has an
107 external log, it is not copied. Internal logs are copied and any out‐
108 standing log transactions are not obfuscated if they contain names.
109 xfs_metadump is a shell wrapper around the xfs_db(8) metadump command.
111
113 xfs_repair(8), xfs_mdrestore(8), xfs_freeze(8), xfs_db(8), xfs_copy(8),
114 xfs(5)
115
117 Email bug reports to linux-xfs@vger.kernel.org.
118 xfs_metadump(8)