Debian Codegraph @

upstream/debian-unstable/man8/xfs_metadump.8

raw
1 .TH xfs_metadump 8
2 .SH NAME
3 xfs_metadump \- copy XFS filesystem metadata to a file
4 .SH SYNOPSIS
5 .B xfs_metadump
6 [
7 .B \-aefFgow
8 ] [
9 .B \-m
10 .I max_extents
11 ] [
12 .B \-l
13 .I logdev
14 ] [
15 .B \-r
16 .I rtdev
17 ] [
18 .B \-v
19 .I version
20 ]
21 .I source
22 .I target
23 .br
24 .B xfs_metadump \-V
25 .SH DESCRIPTION
26 .B xfs_metadump
27 is a debugging tool that copies the metadata from an XFS filesystem to a file.
28 The
29 .I source
30 argument must be the pathname of the device or file
31 containing the XFS filesystem and the
32 .I target
33 argument specifies the destination file name.
34 If
35 .I target
36 is \-, then the output is sent to stdout. This allows the output to be
37 redirected to another program such as a compression application.
38 .PP
39 .B xfs_metadump
40 may only be used to copy unmounted filesystems, or read-only mounted
41 filesystems.
42 .PP
43 .B xfs_metadump
44 does not alter the source filesystem in any way. The
45 .I target
46 image is a contiguous (non-sparse) file containing all the
47 filesystem's metadata and indexes to where the blocks were copied from.
48 .PP
49 By default,
50 .B xfs_metadump
51 obfuscates most file (regular file, directory and symbolic link) names
52 and extended attribute names to allow the dumps to be sent without
53 revealing confidential information. Extended attribute values are zeroed
54 and no data is copied. The only exceptions are file or attribute names
55 that are 4 or less characters in length. Also file names that span extents
56 (this can only occur with the
57 .BR mkfs.xfs (8)
58 options where
59 .B \-n
60 .I size
61 >
62 .B \-b
63 .IR size )
64 are not obfuscated. Names between 5 and 8 characters in length inclusively
65 are partially obfuscated.
66 .PP
67 .B xfs_metadump
68 cannot obfuscate metadata in the filesystem log. Log
69 recovery of an obfuscated metadump image may expose clear-text
70 metadata and/or cause filesystem corruption in the restored image.
71 It is recommended that the source filesystem first be mounted and
72 unmounted, if possible, to ensure that the log is clean.
73 A subsequent invocation of
74 .B xfs_metadump
75 will capture a clean log and obfuscate all metadata correctly.
76 .PP
77 If a metadump must be produced from a filesystem with a dirty log,
78 it is recommended that obfuscation be turned off with -o option, if
79 metadata such as filenames is not considered sensitive. If obfuscation
80 is required on a metadump with a dirty log, please inform the recipient
81 of the metadump image about this situation.
82 .PP
83 The contents of an external log device can be dumped only when using the v2
84 format.
85 Metadump in v2 format can be generated by passing the "-v 2" option.
86 Metadump in v2 format is generated by default if the filesystem has an
87 external log and the metadump version to use is not explicitly mentioned.
88 .PP
89 .B xfs_metadump
90 should not be used for any purposes other than for debugging and reporting
91 filesystem problems. The most common usage scenario for this tool is when
92 .BR xfs_repair (8)
93 fails to repair a filesystem and a metadump image can be sent for
94 analysis.
95 .PP
96 The file generated by
97 .B xfs_metadump
98 can be restored to filesystem image (minus the data) using the
99 .BR xfs_mdrestore (8)
100 tool.
101 .PP
102 .SH OPTIONS
103 .TP
104 .B \-a
105 Copies entire metadata blocks. Normally,
106 .B xfs_metadump
107 will zero any stale
108 bytes interspersed with in-use metadata. Use this option to copy full metadata
109 blocks, to provide more debugging information for a corrupted filesystem. Note
110 that the extra data will be unobfuscated.
111 .TP
112 .B \-e
113 Stops the dump on a read error. Normally, it will ignore read errors and copy
114 all the metadata that is accessible.
115 .TP
116 .B \-f
117 Specifies that the filesystem image to be processed is stored in a regular file
118 (see the
119 .B mkfs.xfs -d
120 file option). This can also happen if an image copy of a filesystem has
121 been made into an ordinary file with
122 .BR xfs_copy (8).
123 .TP
124 .B \-F
125 Specifies that we want to continue even if the superblock magic is not correct.
126 If the source is truly not an XFS filesystem, the resulting image will be useless,
127 and xfs_metadump may crash.
128 .TP
129 .B \-g
130 Shows dump progress. This is sent to stdout if the
131 .I target
132 is a file or to stderr if the
133 .I target
134 is stdout.
135 .TP
136 .BI \-l " logdev"
137 For filesystems which use an external log, this specifies the device where the
138 external log resides.
139 If the v2 metadump format is selected, the contents of the external log will be
140 copied to the metadump.
141 The v2 metadump format will be selected automatically if this option is
142 specified.
143 .TP
144 .B \-m
145 Set the maximum size of an allowed metadata extent. Extremely large metadata
146 extents are likely to be corrupt, and will be skipped if they exceed
147 this value. The default size is 2097151 blocks.
148 .TP
149 .B \-o
150 Disables obfuscation of file names and extended attributes.
151 .TP
152 .BI \-r " rtdev"
153 For filesystems that have a realtime section, this specifies the device where
154 the realtime section resides.
155 If the v2 metadump format is selected, the realtime group superblocks will be
156 copied to the metadump.
157 The v2 metadump format will be selected automatically if the filesystem
158 contains realtime groups.
159 .TP
160 .B \-v
161 The format of the metadump file to be produced.
162 Valid values are 1 and 2.
163 The default metadump format is 1.
164 .TP
165 .B \-w
166 Prints warnings of inconsistent metadata encountered to stderr. Bad metadata
167 is still copied.
168 .TP
169 .B \-V
170 Prints the version number and exits.
171 .SH DIAGNOSTICS
172 .B xfs_metadump
173 returns an exit code of 0 if all readable metadata is successfully copied or
174 1 if a write error occurs or a read error occurs and the
175 .B \-e
176 option used.
177 .SH NOTES
178 As
179 .B xfs_metadump
180 copies metadata only, it does not matter if the
181 .I source
182 filesystem has a realtime section or not. If the filesystem has an external
183 log, it is not copied. Internal logs are copied and any outstanding log
184 transactions are not obfuscated if they contain names.
185 .PP
186 .B xfs_metadump
187 is a shell wrapper around the
188 .BR xfs_db (8)
189 .B metadump
190 command.
191 .SH SEE ALSO
192 .BR xfs_repair (8),
193 .BR xfs_mdrestore (8),
194 .BR xfs_freeze (8),
195 .BR xfs_db (8),
196 .BR xfs_copy (8),
197 .BR xfs (5)
198 .SH BUGS
199 Email bug reports to
200 .BR [email protected] .